@shortlink-org/portolan 0.1.0

package/plugins/gen-markdown/module.go

@@ -0,0 +1,107 @@
+package main
+
+import (
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// renderModules gives schema registries a first-class place in the generated
+// documentation. A module is shared by its publisher and every vendored
+// consumer, so hiding it inside one service loses the relationship readers
+// usually need it for.
+func (s *site) renderModules() {
+	if len(s.cat.Modules) == 0 {
+		return
+	}
+
+	const self = "modules/README.md"
+	var b strings.Builder
+	b.WriteString("# Schema modules\n\n")
+	b.WriteString(s.stamp() + "\n")
+	rows := make([][]string, 0, len(s.cat.Modules))
+	for i := range s.cat.Modules {
+		module := &s.cat.Modules[i]
+		rows = append(rows, []string{
+			s.ref(self, module.ID, orDefault(module.Name, module.ID)),
+			s.ref(self, module.Owner, module.Owner),
+			module.Registry,
+			module.Commit,
+			plural(len(module.Packages), "package"),
+		})
+	}
+	b.WriteString(table([]string{"Module", "Publisher", "Registry", "Commit", "Packages"}, rows))
+	s.b.file(self, b.String())
+
+	for i := range s.cat.Modules {
+		s.renderModule(&s.cat.Modules[i])
+	}
+}
+
+func (s *site) renderModule(module *catalog.ProtoModule) {
+	self := s.pathOf[module.ID]
+	owner := s.services[module.Owner]
+	var b strings.Builder
+	b.WriteString("# " + orDefault(module.Name, module.ID) + "\n\n")
+	b.WriteString(s.stamp() + "\n")
+	b.WriteString(defList([][]string{
+		{"Id", code(module.ID)},
+		{"Registry", module.Registry},
+		{"Publisher", s.ref(self, module.Owner, module.Owner)},
+		{"Commit", code(module.Commit)},
+		{"Digest", code(module.Digest)},
+		{"Source", s.source(self, module.Source, owner)},
+	}))
+
+	packages := make([][]string, 0, len(module.Packages))
+	for _, pkg := range module.Packages {
+		packages = append(packages, []string{code(pkg)})
+	}
+	section(&b, "Packages", table([]string{"Package"}, packages))
+
+	files := make([][]string, 0, len(module.Files))
+	for _, file := range module.Files {
+		files = append(files, []string{s.source(self, file, owner)})
+	}
+	section(&b, "Files", table([]string{"File"}, files))
+
+	deps := make([][]string, 0, len(module.Deps))
+	for _, id := range module.Deps {
+		deps = append(deps, []string{s.ref(self, id, id)})
+	}
+	section(&b, "Dependencies", table([]string{"Module"}, deps))
+
+	users := make([][]string, 0)
+	for i := range s.cat.Contexts {
+		for j := range s.cat.Contexts[i].Services {
+			svc := &s.cat.Contexts[i].Services[j]
+			for _, id := range svc.Modules {
+				if id != module.ID {
+					continue
+				}
+				access := "reads"
+				if svc.ID == module.Owner {
+					access = "publishes"
+				}
+				users = append(users, []string{s.ref(self, svc.ID, svc.Name), access})
+			}
+		}
+	}
+	section(&b, "Used by", table([]string{"Service", "Access"}, users))
+
+	var interfaces strings.Builder
+	for i := range s.cat.Contexts {
+		for j := range s.cat.Contexts[i].Services {
+			svc := &s.cat.Contexts[i].Services[j]
+			for k := range svc.Provides {
+				provided := &svc.Provides[k]
+				if provided.Module == module.ID {
+					interfaces.WriteString(s.providesBlock(self, []catalog.RpcService{*provided}, svc))
+				}
+			}
+		}
+	}
+	section(&b, "Interfaces", interfaces.String())
+
+	s.b.file(self, b.String())
+}

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

@@ -0,0 +1,16 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "Heading of the index page. The catalog does not name the estate, so this is the one thing the generator cannot derive.",
+      "examples": ["Example estate"]
+    },
+    "sourceBaseUrl": {
+      "type": "string",
+      "description": "Stable forge tree URL used to link source locations, for example https://github.com/acme/shop/blob/main. External repositories use their immutable catalog pins.",
+      "examples": ["https://github.com/acme/shop/blob/main"]
+    }
+  }
+}

package/plugins/gen-markdown/plugin.go

@@ -0,0 +1,39 @@
+// Package main is portolan-gen-markdown: a catalog in, a directory of markdown
+// out.
+//
+// The plugin never touches the filesystem. It is handed a catalog on stdin and
+// answers with the files it would like written; the host writes them. That is
+// what lets the same binary run as a sandboxed wasm module with no directory
+// preopened at all, and it is what makes `--check` cheap: the host compares
+// what came back against what is on disk without the plugin knowing there is a
+// disk.
+package main
+
+import (
+	"fmt"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// Options are this plugin's own settings, passed through from the manifest.
+type Options struct {
+	// Title heads the index page. The catalog does not name the estate, so
+	// this is the one thing the plugin cannot derive.
+	Title string `json:"title,omitempty"`
+	// SourceBaseURL is the stable tree URL for this repository, such as a
+	// default branch. External repositories still use their immutable RepoPin.
+	SourceBaseURL string `json:"sourceBaseUrl,omitempty"`
+}
+
+// builder is plugin.Builder with the formatting the render code wants. The
+// shared one deliberately takes a plain string: a protocol type that knows
+// about printf verbs is a protocol type doing somebody else's job.
+type builder struct {
+	plugin.Builder
+}
+
+func (b *builder) file(name, contents string) { b.File(name, contents) }
+
+func (b *builder) warn(ref, format string, args ...any) {
+	b.Warn(ref, fmt.Sprintf(format, args...))
+}

package/plugins/gen-markdown/quality_test.go

@@ -0,0 +1,176 @@
+package main
+
+import (
+	"encoding/json"
+	"net/url"
+	"os"
+	"path"
+	"regexp"
+	"slices"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+var localLink = regexp.MustCompile(`\]\(([^\s)]+)(?:\s+[^)]*)?\)`)
+var explicitAnchor = regexp.MustCompile(`<a id="([^"]+)"></a>`)
+
+func fixtureCatalog(t *testing.T) catalog.Catalog {
+	t.Helper()
+	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)
+	}
+	return cat
+}
+
+func renderedFiles(resp plugin.Response) map[string]string {
+	out := make(map[string]string, len(resp.Files))
+	for _, file := range resp.Files {
+		out[file.Name] = file.Contents
+	}
+	return out
+}
+
+func TestEveryGeneratedLinkAndAnchorResolves(t *testing.T) {
+	files := renderedFiles(render(plugin.Request{Catalog: fixtureCatalog(t)}, Options{}))
+	for name, contents := range files {
+		// This concatenation keeps each page's original relative links and names
+		// the page in an HTML comment; it is not itself a linkable directory.
+		if name == llmsFullPage {
+			continue
+		}
+		for _, match := range localLink.FindAllStringSubmatch(contents, -1) {
+			target := match[1]
+			if strings.HasPrefix(target, "#") {
+				target = name + target
+			}
+			if parsed, err := url.Parse(target); err != nil || parsed.IsAbs() {
+				continue
+			}
+			parts := strings.SplitN(target, "#", 2)
+			file := path.Clean(path.Join(path.Dir(name), parts[0]))
+			body, ok := files[file]
+			if !ok {
+				t.Errorf("%s links to missing %s", name, target)
+				continue
+			}
+			if len(parts) == 2 && parts[1] != "" && !hasAnchor(body, parts[1]) {
+				t.Errorf("%s links to missing anchor %s in %s", name, parts[1], file)
+			}
+		}
+	}
+}
+
+func hasAnchor(markdown, wanted string) bool {
+	for _, match := range explicitAnchor.FindAllStringSubmatch(markdown, -1) {
+		if match[1] == wanted {
+			return true
+		}
+	}
+	for _, line := range strings.Split(markdown, "\n") {
+		if heading := strings.TrimLeft(line, "#"); heading != line && strings.HasPrefix(heading, " ") && anchor(strings.TrimSpace(heading)) == wanted {
+			return true
+		}
+	}
+	return false
+}
+
+func TestRenderingIgnoresNonSemanticEntityOrder(t *testing.T) {
+	cat := fixtureCatalog(t)
+	want := renderedFiles(render(plugin.Request{Catalog: cat}, Options{}))
+	slices.Reverse(cat.Contexts)
+	for i := range cat.Contexts {
+		slices.Reverse(cat.Contexts[i].Services)
+		for j := range cat.Contexts[i].Services {
+			slices.Reverse(cat.Contexts[i].Services[j].Aggregates)
+			slices.Reverse(cat.Contexts[i].Services[j].Provides)
+			slices.Reverse(cat.Contexts[i].Services[j].Consumes)
+		}
+	}
+	slices.Reverse(cat.Stores)
+	slices.Reverse(cat.Modules)
+	slices.Reverse(cat.Flows)
+	slices.Reverse(cat.Adrs)
+	slices.Reverse(cat.Terms)
+	slices.Reverse(cat.Externals)
+	got := renderedFiles(render(plugin.Request{Catalog: cat}, Options{}))
+	if !reflectFiles(want, got) {
+		t.Fatal("permuting entity sets changed the generated bytes")
+	}
+}
+
+func reflectFiles(a, b map[string]string) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for name, value := range a {
+		if b[name] != value {
+			return false
+		}
+	}
+	return true
+}
+
+func TestSemanticFieldsAndImmutableSourcesAreRendered(t *testing.T) {
+	repo := "https://github.com/example/billing/blob/main"
+	cat := fixtureCatalog(t)
+	cat.Flows[0].Trigger = &catalog.FlowTrigger{Kind: "callback", Label: "POST /callbacks/paid", Confidence: "high"}
+	files := renderedFiles(render(plugin.Request{Catalog: cat}, Options{SourceBaseURL: repo}))
+	service := files["billing/invoices/README.md"]
+	for _, want := range []string{"Schema modules", "Channels", "GET", "RaiseRequest", "server", "deprecated", "flow.raise-invoice#s3", repo + "/examples/billing/api/invoices.proto"} {
+		if !strings.Contains(service, want) {
+			t.Errorf("service page omits %q", want)
+		}
+	}
+	if !strings.Contains(files["modules/example-billing.md"], "Billing contracts") {
+		t.Error("module page was not generated")
+	}
+	flow := files["flows/"+cat.Flows[0].Slug+".md"]
+	if !strings.Contains(flow, "**Trigger:** `callback` · POST /callbacks/paid") || !strings.Contains(flow, "**Root confidence:** high") {
+		t.Error("flow trigger evidence was not rendered")
+	}
+}
+
+func TestNeutralComponentDoesNotPretendToHaveADomainModel(t *testing.T) {
+	cat := catalog.Catalog{
+		GeneratedAt: "2026-09-06T00:00:00Z",
+		Commit:      "abc",
+		Contexts: []catalog.BoundedContext{{
+			ID: "avia", Slug: "avia", Name: "Avia", Kind: catalog.GroupKindSystem,
+			Services: []catalog.Service{{
+				ID: "avia.support", Slug: "support", Name: "Support", Kind: catalog.ComponentKindApplication,
+				Technologies: []string{"Go", "Kafka"}, Provides: []catalog.RpcService{}, Consumes: []catalog.RpcCall{}, Aggregates: []catalog.Aggregate{},
+			}},
+		}},
+		Defs: map[string]catalog.TypeDef{}, Flows: []catalog.Flow{}, Adrs: []catalog.Adr{},
+	}
+	files := renderedFiles(render(plugin.Request{Catalog: cat}, Options{}))
+	group := files["avia/README.md"]
+	component := files["avia/support/README.md"]
+	if !strings.Contains(group, "## Components") || !strings.Contains(group, "Technologies") {
+		t.Fatal(group)
+	}
+	if !strings.Contains(component, "**Kind:** application") || !strings.Contains(component, "Go, Kafka") {
+		t.Fatal(component)
+	}
+	if strings.Contains(component, "## Aggregates") {
+		t.Fatal("neutral component gained an empty DDD section:\n" + component)
+	}
+}
+
+func TestExternalSourceUsesItsImmutablePin(t *testing.T) {
+	owner := &catalog.Service{Repo: "gitlab.example/acme/payments", Path: "vendor/repos/acme/payments"}
+	s := &site{cat: catalog.Catalog{Repos: []catalog.RepoPin{{Repo: owner.Repo, Commit: strings.Repeat("b", 40)}}}, opts: Options{SourceBaseURL: "https://github.com/example/billing/blob/main"}}
+	got := s.source("billing/README.md", "vendor/repos/acme/payments/api/openapi.yaml:12", owner)
+	want := "https://gitlab.example/acme/payments/-/blob/" + strings.Repeat("b", 40) + "/api/openapi.yaml#L12"
+	if !strings.Contains(got, want) {
+		t.Fatalf("source link = %s", got)
+	}
+}

package/plugins/gen-markdown/redis_test.go

@@ -0,0 +1,38 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+func TestRendersRedisKeyPatterns(t *testing.T) {
+	cat := catalog.Catalog{
+		Contexts: []catalog.BoundedContext{{
+			ID: "sales", Slug: "sales", Name: "Sales", Services: []catalog.Service{{
+				ID: "sales.catalog", Slug: "catalog", Name: "Catalog", Provides: []catalog.RpcService{}, Consumes: []catalog.RpcCall{}, Aggregates: []catalog.Aggregate{}, Stores: []string{"sales.catalog.redis"},
+			}},
+		}},
+		Defs: map[string]catalog.TypeDef{}, Flows: []catalog.Flow{}, Adrs: []catalog.Adr{},
+		Stores: []catalog.Store{{
+			ID: "sales.catalog.redis", Slug: "redis", Name: "Catalog Redis", Kind: catalog.StoreKindRedis, Owner: "sales.catalog", Tables: []catalog.Table{},
+			Keyspaces: []catalog.RedisKeyspace{{Pattern: "session:{id}", Operations: []catalog.RedisOperation{catalog.RedisOperationRead, catalog.RedisOperationWrite}, TTL: "24h", Value: "Session", Source: "cache.go:20"}},
+		}},
+	}
+
+	response := render(plugin.Request{Catalog: cat}, Options{})
+	var page string
+	for _, file := range response.Files {
+		if file.Name == "sales/catalog/stores/redis.md" {
+			page = file.Contents
+			break
+		}
+	}
+	for _, want := range []string{"## Redis key patterns", "`session:{id}`", "read, write", "`Session`", "`24h`", "cache.go"} {
+		if !strings.Contains(page, want) {
+			t.Fatalf("Redis store page does not contain %q:\n%s", want, page)
+		}
+	}
+}