@shortlink-org/portolan 0.1.0 → 0.2.0

package/plugins/gen-markdown/module.go

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

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

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

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

package/plugins/gen-markdown/render.go

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