@shortlink-org/portolan 0.1.0

package/plugins/gen-markdown/adr.go

@@ -0,0 +1,162 @@
+package main
+
+import (
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+func (s *site) renderAdrs() {
+	if len(s.cat.Adrs) == 0 {
+		return
+	}
+
+	const self = "adr/README.md"
+
+	var b strings.Builder
+	b.WriteString("# Decision records\n\n")
+	b.WriteString(s.stamp() + "\n")
+
+	rows := make([][]string, 0, len(s.cat.Adrs))
+	for i := range s.cat.Adrs {
+		adr := &s.cat.Adrs[i]
+		rows = append(rows, []string{
+			s.ref(self, adr.ID, adr.ID),
+			adr.Title,
+			string(adr.Status),
+			adr.Date,
+			s.scopeRef(self, adr.Scope),
+		})
+	}
+	b.WriteString(table([]string{"ADR", "Title", "Status", "Date", "Scope"}, rows))
+
+	s.b.file(self, b.String())
+
+	for i := range s.cat.Adrs {
+		s.renderAdr(&s.cat.Adrs[i])
+	}
+}
+
+func (s *site) renderAdr(adr *catalog.Adr) {
+	self := s.pathOf[adr.ID]
+
+	var b strings.Builder
+	b.WriteString("# " + adr.ID + " — " + adr.Title + "\n\n")
+	b.WriteString(s.stamp() + "\n")
+
+	meta := [][]string{
+		{"Status", string(adr.Status)},
+		{"Date", adr.Date},
+		{"Scope", s.scopeRef(self, adr.Scope)},
+		{"Source", s.source(self, adr.Source, s.adrOwner(adr))},
+	}
+	if adr.Created != nil {
+		meta = append(meta, []string{"Committed", commitLine(adr.Created)})
+	}
+	if adr.Revised != nil {
+		meta = append(meta, []string{"Revised", commitLine(adr.Revised)})
+	}
+	if adr.Note != "" {
+		meta = append(meta, []string{"Note", adr.Note})
+	}
+	if adr.SupersededBy != "" {
+		// Worth putting in the header rather than at the bottom: everything
+		// below it is history the moment this is set.
+		meta = append(meta, []string{"Superseded by", s.ref(self, adr.SupersededBy, adr.SupersededBy)})
+	}
+	if len(adr.Supersedes) > 0 {
+		refs := make([]string, 0, len(adr.Supersedes))
+		for _, id := range adr.Supersedes {
+			refs = append(refs, s.ref(self, id, id))
+		}
+		meta = append(meta, []string{"Supersedes", strings.Join(refs, ", ")})
+	}
+	b.WriteString(defList(meta))
+
+	// The body is the record. It is frozen history and is never regenerated
+	// from the current catalog, so it goes in whole, one level down.
+	if rendered := body(adr.Body, adr.Title); rendered != "" {
+		b.WriteString("\n" + rendered + "\n")
+	}
+
+	section(&b, "Relates to", s.relatesList(self, adr.Relates))
+
+	s.b.file(self, b.String())
+}
+
+func (s *site) adrOwner(adr *catalog.Adr) *catalog.Service {
+	if adr.Scope.Kind == "service" {
+		return s.services[adr.Scope.Service]
+	}
+	return s.serviceForSource(adr.Source)
+}
+
+func (s *site) relatesList(from string, relates catalog.AdrRelates) string {
+	var b strings.Builder
+
+	groups := []struct {
+		label string
+		ids   []string
+	}{
+		{"Services", relates.Services},
+		{"Events", relates.Events},
+		{"Flows", relates.Flows},
+	}
+
+	for _, group := range groups {
+		if len(group.ids) == 0 {
+			continue
+		}
+
+		refs := make([]string, 0, len(group.ids))
+		for _, id := range group.ids {
+			// An event id belongs to the aggregate page that publishes it, so
+			// it is resolved through its owner rather than looked up directly.
+			if _, ok := s.eventPage[id]; ok {
+				refs = append(refs, s.eventRef(from, id, id))
+
+				continue
+			}
+			refs = append(refs, s.ref(from, id, id))
+		}
+		b.WriteString("- **" + group.label + ":** " + strings.Join(refs, ", ") + "\n")
+	}
+
+	return b.String()
+}
+
+func (s *site) scopeRef(from string, scope catalog.AdrScope) string {
+	switch scope.Kind {
+	case "context":
+		return s.ref(from, scope.Context, scope.Context)
+	case "service":
+		return s.ref(from, scope.Service, scope.Service)
+	default:
+		return "org"
+	}
+}
+
+// commitLine is who and when, and the commit itself short enough to read:
+// "Viktor Login, 2024-09-10 (`a6181fe`)".
+func commitLine(c *catalog.AdrCommit) string {
+	date := c.Date
+	if len(date) >= 10 {
+		date = date[:10]
+	}
+	sha := c.Commit
+	if len(sha) > 7 {
+		sha = sha[:7]
+	}
+	parts := []string{}
+	if c.Author != "" {
+		parts = append(parts, c.Author)
+	}
+	if date != "" {
+		parts = append(parts, date)
+	}
+	line := strings.Join(parts, ", ")
+	if sha != "" {
+		line += " (`" + sha + "`)"
+	}
+	return strings.TrimSpace(line)
+}

package/plugins/gen-markdown/aggregate.go

@@ -0,0 +1,362 @@
+package main
+
+import (
+	"strconv"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+func (s *site) renderAggregate(svc *catalog.Service, agg *catalog.Aggregate) {
+	self := s.pathOf[agg.ID]
+
+	var b strings.Builder
+	b.WriteString("# " + agg.Name + "\n\n")
+	b.WriteString(s.stamp() + "\n")
+
+	b.WriteString(defList([][]string{
+		{"Id", code(agg.ID)},
+		{"Service", s.ref(self, svc.ID, svc.Name)},
+		{"Root", code(agg.Root)},
+	}))
+
+	if readme := body(agg.Readme, agg.Name); readme != "" {
+		b.WriteString("\n" + readme + "\n")
+	}
+
+	if !hasBlock(agg.Entities, agg.Root) {
+		s.b.warn(agg.ID, "aggregate %q names %q as its root, which is not one of its entities", agg.ID, agg.Root)
+	}
+
+	section(&b, "Entities", s.blocks(self, agg.Entities, agg.Root))
+	section(&b, "Value objects", s.blocks(self, agg.ValueObjects, ""))
+	section(&b, "Enums", s.enums(agg.Enums))
+	section(&b, "Lifecycle", s.lifecycle(self, svc, agg))
+	section(&b, "Operations", s.operationsTable(agg))
+	section(&b, "Events", s.eventsBlock(self, svc, agg))
+
+	s.b.file(self, b.String())
+}
+
+// lifecycle draws the root's state machine as the code wrote it down, and
+// lists the moves under it with the event each one publishes. The first
+// state is where a new root starts; a state nothing leads out of ends.
+func (s *site) lifecycle(from string, svc *catalog.Service, agg *catalog.Aggregate) string {
+	lc := agg.Lifecycle
+	if lc == nil || len(lc.States) == 0 {
+		return ""
+	}
+	alias := func(state string) string {
+		var b strings.Builder
+		for _, r := range state {
+			if r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r >= '0' && r <= '9' {
+				b.WriteRune(r)
+			} else {
+				b.WriteByte('_')
+			}
+		}
+		return b.String()
+	}
+	leads := map[string]bool{}
+	for _, t := range lc.Transitions {
+		if t.From != t.To {
+			leads[t.From] = true
+		}
+	}
+	eventName := func(id string) string {
+		for i := range agg.Events {
+			if agg.Events[i].ID == id {
+				return agg.Events[i].Name
+			}
+		}
+		return id
+	}
+
+	var d strings.Builder
+	d.WriteString("stateDiagram-v2\n")
+	for _, state := range lc.States {
+		if alias(state) != state {
+			d.WriteString("    state \"" + mermaidText(state) + "\" as " + alias(state) + "\n")
+		}
+	}
+	d.WriteString("    [*] --> " + alias(lc.States[0]) + "\n")
+	for _, t := range lc.Transitions {
+		label := t.On
+		if t.Emits != "" {
+			label += " · " + eventName(t.Emits)
+		}
+		d.WriteString("    " + alias(t.From) + " --> " + alias(t.To) + ": " + mermaidText(label) + "\n")
+	}
+	for _, state := range lc.States {
+		if !leads[state] {
+			d.WriteString("    " + alias(state) + " --> [*]\n")
+		}
+	}
+
+	rows := make([][]string, 0, len(lc.Transitions))
+	for _, t := range lc.Transitions {
+		emits := ""
+		if t.Emits != "" {
+			emits = s.ref(from, t.Emits, eventName(t.Emits))
+		}
+		rows = append(rows, []string{code(t.From), code(t.To), code(t.On), emits, s.source(from, t.Source, svc)})
+	}
+
+	return fence("mermaid", d.String()) + "\n" + table([]string{"From", "To", "On", "Emits", "Source"}, rows)
+}
+
+func hasBlock(blocks []catalog.Block, name string) bool {
+	for i := range blocks {
+		if blocks[i].Name == name {
+			return true
+		}
+	}
+
+	return false
+}
+
+// blocks renders entities or value objects. A block is either a shape of its
+// own or a name for a shared one; both are shown with their fields, because a
+// reader asking what a value object holds should not have to follow a link to
+// find out.
+// enums lists each closed set with its values in declaration order: what a
+// consumer has to handle, next to the doc that says when each one comes.
+func (s *site) enums(enums []catalog.Enum) string {
+	var b strings.Builder
+
+	for i := range enums {
+		set := &enums[i]
+
+		heading := set.Name
+		if set.Deprecated {
+			heading += " — deprecated"
+		}
+		b.WriteString("### " + heading + "\n\n")
+
+		if set.Doc != "" {
+			b.WriteString(set.Doc + "\n\n")
+		}
+
+		rows := make([][]string, 0, len(set.Values))
+		for _, value := range set.Values {
+			name := code(value.Name)
+			if value.Deprecated {
+				name += " (deprecated)"
+			}
+			rows = append(rows, []string{name, value.Doc})
+		}
+		if rendered := table([]string{"Value", "Doc"}, rows); rendered != "" {
+			b.WriteString(rendered + "\n")
+		}
+	}
+
+	return b.String()
+}
+
+func (s *site) blocks(from string, blocks []catalog.Block, root string) string {
+	var b strings.Builder
+
+	for i := range blocks {
+		block := &blocks[i]
+
+		heading := block.Name
+		if block.Name == root {
+			heading += " — aggregate root"
+		}
+		b.WriteString("### " + heading + "\n\n")
+
+		if block.Doc != "" {
+			b.WriteString(block.Doc + "\n\n")
+		}
+
+		fields := block.Fields
+		if block.Ref != "" {
+			def, ok := s.cat.Defs[block.Ref]
+			if !ok {
+				s.b.warn(block.ID, "%q refers to shared type %q, which this catalog does not define", block.ID, block.Ref)
+			} else {
+				fields = def.Fields
+			}
+			b.WriteString("Shared type " + s.defRef(from, block.Ref) + ".\n\n")
+		}
+
+		if rendered := s.fieldTable(from, fields); rendered != "" {
+			b.WriteString(rendered + "\n")
+		}
+	}
+
+	return b.String()
+}
+
+func (s *site) operationsTable(agg *catalog.Aggregate) string {
+	// Whether this service records what exposes an operation at all. A catalog
+	// written before anything read a transport layer says nothing either way,
+	// and printing "internal" from that silence would be inventing.
+	recorded := false
+	for i := range agg.Operations {
+		if len(agg.Operations[i].ExposedBy) > 0 {
+			recorded = true
+
+			break
+		}
+	}
+
+	rows := make([][]string, 0, len(agg.Operations))
+	for i := range agg.Operations {
+		op := &agg.Operations[i]
+
+		exposed := ""
+		switch {
+		case len(op.ExposedBy) > 0:
+			methods := make([]string, 0, len(op.ExposedBy))
+			for _, method := range op.ExposedBy {
+				methods = append(methods, code(method))
+			}
+			exposed = strings.Join(methods, ", ")
+		case recorded:
+			exposed = "*internal*"
+		}
+
+		rows = append(rows, []string{code(op.ID), string(op.Kind), exposed, op.Doc})
+	}
+
+	return table([]string{"Operation", "Kind", "Exposed by", "Doc"}, rows)
+}
+
+// eventsBlock renders every version of every event, oldest first.
+//
+// Older versions are kept rather than collapsed into the latest: a consumer
+// reading this page is very often the one still on v1, and a page that shows
+// only what the publisher sends today cannot answer their question.
+func (s *site) eventsBlock(from string, svc *catalog.Service, agg *catalog.Aggregate) string {
+	var b strings.Builder
+
+	for i := range agg.Events {
+		event := &agg.Events[i]
+		b.WriteString("<a id=\"event-" + anchorID(event.ID) + "\"></a>\n")
+		b.WriteString("### " + event.Name + "\n\n")
+		b.WriteString(code(event.ID) + "\n")
+
+		if event.Wire != nil {
+			line := "On the wire as " + code(event.Wire.Name)
+			if event.Wire.Channel != "" {
+				line += ", on " + code(event.Wire.Channel)
+			}
+			b.WriteString("\n" + line + ".\n")
+		}
+
+		if len(event.Versions) == 0 {
+			s.b.warn(event.ID, "event %q has no versions", event.ID)
+		}
+
+		consumers := make([][]string, 0, len(event.Consumers))
+		for _, consumer := range event.Consumers {
+			consumers = append(consumers, []string{
+				s.ref(from, consumer.Service, consumer.Service),
+				string(consumer.Status),
+				s.viaRef(from, consumer.Via),
+				consumer.Note,
+			})
+		}
+		if rendered := table([]string{"Consumer", "Status", "Via", "Note"}, consumers); rendered != "" {
+			b.WriteString("\n" + rendered)
+		}
+
+		for j := range event.Versions {
+			version := &event.Versions[j]
+
+			label := version.Version
+			if j == len(event.Versions)-1 {
+				label += " — current"
+			}
+			b.WriteString("\n#### " + label + "\n\n")
+
+			if version.Doc != "" {
+				b.WriteString(version.Doc + "\n\n")
+			}
+			if version.Source != "" {
+				b.WriteString("Source: " + s.source(from, version.Source, svc) + "\n\n")
+			}
+			b.WriteString(s.fieldTable(from, version.Fields))
+		}
+		b.WriteString("\n")
+	}
+
+	return b.String()
+}
+
+func (s *site) fieldTable(from string, fields []catalog.Field) string {
+	rows := make([][]string, 0, len(fields))
+	for i := range fields {
+		field := &fields[i]
+
+		typ := code(field.Type)
+		if field.Ref != "" {
+			typ = s.defRef(from, field.Ref)
+		}
+		rows = append(rows, []string{code(field.Name), typ, field.Doc})
+	}
+
+	return table([]string{"Field", "Type", "Doc"}, rows)
+}
+
+// defRef links a shared type to its entry on the types page. Shared types have
+// no page of their own: what a reader wants from `Money` is the same six lines
+// wherever it is mentioned, and six lines do not deserve twenty files.
+func (s *site) defRef(from, key string) string {
+	if _, ok := s.cat.Defs[key]; !ok {
+		return code(key)
+	}
+
+	return "[" + code(key) + "](" + rel(from, typesPage) + "#type-" + anchorID(key) + ")"
+}
+
+const typesPage = "types.md"
+
+// anchor is a GitHub-flavoured heading anchor: lowercased, spaces to dashes,
+// everything else dropped.
+func anchor(heading string) string {
+	var b strings.Builder
+	for _, r := range strings.ToLower(heading) {
+		switch {
+		case r >= 'a' && r <= 'z', r >= '0' && r <= '9', r == '-', r == '_':
+			b.WriteRune(r)
+		case r == ' ':
+			b.WriteRune('-')
+		}
+	}
+
+	return b.String()
+}
+
+func (s *site) renderTypes() {
+	if len(s.cat.Defs) == 0 {
+		return
+	}
+
+	var b strings.Builder
+	b.WriteString("# Shared types\n\n")
+	b.WriteString(s.stamp() + "\n")
+	b.WriteString("Types named by more than one aggregate, event or message. A field that\n")
+	b.WriteString("refers to one of these is knowably the same shape everywhere it appears.\n")
+
+	for _, key := range sortedDefKeys(s.cat.Defs) {
+		def := s.cat.Defs[key]
+		b.WriteString("\n<a id=\"type-" + anchorID(key) + "\"></a>\n")
+		b.WriteString("\n## " + key + "\n\n")
+		b.WriteString(s.fieldTable(typesPage, def.Fields))
+	}
+
+	s.b.file(typesPage, b.String())
+}
+
+func plural(n int, word string, irregular ...string) string {
+	if n == 1 {
+		return "1 " + word
+	}
+	if len(irregular) > 0 {
+		return strconv.Itoa(n) + " " + irregular[0]
+	}
+
+	return strconv.Itoa(n) + " " + word + "s"
+}

package/plugins/gen-markdown/canonical.go

@@ -0,0 +1,93 @@
+package main
+
+import (
+	"slices"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// canonicalCatalog sorts only collections whose order carries no meaning.
+// Fields, event versions, lifecycle transitions, flow participants and flow
+// nodes deliberately keep their declared order.
+func canonicalCatalog(cat catalog.Catalog) catalog.Catalog {
+	out := cat
+	out.Contexts = slices.Clone(cat.Contexts)
+	slices.SortFunc(out.Contexts, func(a, b catalog.BoundedContext) int { return strings.Compare(a.ID, b.ID) })
+	for i := range out.Contexts {
+		ctx := &out.Contexts[i]
+		ctx.Services = slices.Clone(ctx.Services)
+		slices.SortFunc(ctx.Services, func(a, b catalog.Service) int { return strings.Compare(a.ID, b.ID) })
+		for j := range ctx.Services {
+			svc := &ctx.Services[j]
+			svc.Aggregates = slices.Clone(svc.Aggregates)
+			slices.SortFunc(svc.Aggregates, func(a, b catalog.Aggregate) int { return strings.Compare(a.ID, b.ID) })
+			for k := range svc.Aggregates {
+				agg := &svc.Aggregates[k]
+				agg.Entities = slices.Clone(agg.Entities)
+				slices.SortFunc(agg.Entities, func(a, b catalog.Block) int { return strings.Compare(a.ID, b.ID) })
+				agg.ValueObjects = slices.Clone(agg.ValueObjects)
+				slices.SortFunc(agg.ValueObjects, func(a, b catalog.Block) int { return strings.Compare(a.ID, b.ID) })
+				agg.Operations = slices.Clone(agg.Operations)
+				slices.SortFunc(agg.Operations, func(a, b catalog.Operation) int { return strings.Compare(a.ID, b.ID) })
+				agg.Events = slices.Clone(agg.Events)
+				slices.SortFunc(agg.Events, func(a, b catalog.Event) int { return strings.Compare(a.ID, b.ID) })
+				agg.Enums = slices.Clone(agg.Enums)
+				slices.SortFunc(agg.Enums, func(a, b catalog.Enum) int { return strings.Compare(a.ID, b.ID) })
+			}
+			svc.Provides = canonicalProvides(svc.Provides)
+			svc.Consumes = slices.Clone(svc.Consumes)
+			slices.SortFunc(svc.Consumes, func(a, b catalog.RpcCall) int { return strings.Compare(a.ID, b.ID) })
+			svc.Stores = sortedStrings(svc.Stores)
+			svc.Modules = sortedStrings(svc.Modules)
+			svc.Channels = slices.Clone(svc.Channels)
+			slices.SortFunc(svc.Channels, func(a, b catalog.Channel) int { return strings.Compare(a.Address, b.Address) })
+		}
+	}
+	out.Stores = slices.Clone(cat.Stores)
+	slices.SortFunc(out.Stores, func(a, b catalog.Store) int { return strings.Compare(a.ID, b.ID) })
+	out.Flows = slices.Clone(cat.Flows)
+	slices.SortFunc(out.Flows, func(a, b catalog.Flow) int { return strings.Compare(a.ID, b.ID) })
+	out.Adrs = slices.Clone(cat.Adrs)
+	slices.SortFunc(out.Adrs, func(a, b catalog.Adr) int { return strings.Compare(a.ID, b.ID) })
+	out.Modules = slices.Clone(cat.Modules)
+	slices.SortFunc(out.Modules, func(a, b catalog.ProtoModule) int { return strings.Compare(a.ID, b.ID) })
+	for i := range out.Modules {
+		out.Modules[i].Packages = sortedStrings(out.Modules[i].Packages)
+		out.Modules[i].Files = sortedStrings(out.Modules[i].Files)
+		out.Modules[i].Deps = sortedStrings(out.Modules[i].Deps)
+	}
+	out.Terms = slices.Clone(cat.Terms)
+	slices.SortFunc(out.Terms, func(a, b catalog.Term) int {
+		if a.Context != b.Context {
+			return strings.Compare(a.Context, b.Context)
+		}
+		return strings.Compare(strings.ToLower(a.Name), strings.ToLower(b.Name))
+	})
+	out.Externals = slices.Clone(cat.Externals)
+	slices.SortFunc(out.Externals, func(a, b catalog.External) int { return strings.Compare(a.ID, b.ID) })
+	for i := range out.Externals {
+		out.Externals[i].Provides = canonicalProvides(out.Externals[i].Provides)
+	}
+	return out
+}
+
+func canonicalProvides(input []catalog.RpcService) []catalog.RpcService {
+	out := slices.Clone(input)
+	slices.SortFunc(out, func(a, b catalog.RpcService) int { return strings.Compare(a.ID, b.ID) })
+	for i := range out {
+		out[i].Methods = slices.Clone(out[i].Methods)
+		slices.SortFunc(out[i].Methods, func(a, b catalog.RpcMethod) int { return strings.Compare(a.Name, b.Name) })
+		out[i].Messages = slices.Clone(out[i].Messages)
+		slices.SortFunc(out[i].Messages, func(a, b catalog.RpcMessage) int { return strings.Compare(a.Name, b.Name) })
+		out[i].Enums = slices.Clone(out[i].Enums)
+		slices.SortFunc(out[i].Enums, func(a, b catalog.RpcEnum) int { return strings.Compare(a.Name, b.Name) })
+	}
+	return out
+}
+
+func sortedStrings(input []string) []string {
+	out := slices.Clone(input)
+	slices.Sort(out)
+	return out
+}

package/plugins/gen-markdown/context.go

@@ -0,0 +1,90 @@
+package main
+
+import (
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+func (s *site) renderContext(ctx *catalog.BoundedContext) {
+	self := s.pathOf[ctx.ID]
+
+	var b strings.Builder
+	b.WriteString("# " + ctx.Name + "\n\n")
+	b.WriteString(s.stamp() + "\n")
+
+	meta := [][]string{{"Id", code(ctx.ID)}}
+	if ctx.Kind != "" {
+		meta = append(meta, []string{"Kind", string(ctx.Kind)})
+	}
+	if ctx.Classification != "" {
+		meta = append(meta, []string{"Classification", string(ctx.Classification)})
+	}
+	b.WriteString(defList(meta))
+
+	if ctx.Summary != "" {
+		b.WriteString("\n" + ctx.Summary + "\n")
+	}
+
+	neutral := ctx.Kind != "" && ctx.Kind != catalog.GroupKindBoundedContext
+	rows := make([][]string, 0, len(ctx.Services))
+	for i := range ctx.Services {
+		svc := &ctx.Services[i]
+		if neutral {
+			rows = append(rows, []string{
+				s.ref(self, svc.ID, svc.Name),
+				string(svc.Kind),
+				strings.Join(svc.Technologies, ", "),
+				code(svc.Path),
+			})
+			continue
+		}
+		aggregates := make([]string, 0, len(svc.Aggregates))
+		for j := range svc.Aggregates {
+			aggregates = append(aggregates, svc.Aggregates[j].Name)
+		}
+		rows = append(rows, []string{
+			s.ref(self, svc.ID, svc.Name),
+			code(svc.Path),
+			strings.Join(aggregates, ", "),
+		})
+	}
+	title := "Services"
+	firstColumn := "Service"
+	headings := []string{firstColumn, "Path", "Aggregates"}
+	if neutral {
+		title = "Components"
+		firstColumn = "Component"
+		headings = []string{firstColumn, "Kind", "Technologies", "Path"}
+	}
+	section(&b, title, table(headings, rows))
+
+	// Before the decisions, because the decisions are written in these words.
+	if terms := s.termsOf[ctx.ID]; len(terms) > 0 {
+		section(&b, "Language", "- "+link("Glossary", self, s.glossaryPath(ctx))+
+			" — "+plural(len(terms), "term")+" this context spells one way\n")
+	}
+
+	section(&b, "Decisions", s.adrTable(self, s.adrsFor[ctx.ID]))
+
+	s.b.file(self, b.String())
+	s.renderGlossary(ctx)
+
+	for i := range ctx.Services {
+		s.renderService(ctx, &ctx.Services[i])
+	}
+}
+
+func (s *site) adrTable(from string, adrs []*catalog.Adr) string {
+	rows := make([][]string, 0, len(adrs))
+	for _, adr := range adrs {
+		rows = append(rows, []string{
+			s.ref(from, adr.ID, adr.ID),
+			adr.Title,
+			string(adr.Status),
+			adr.Date,
+		})
+	}
+
+	return table([]string{"ADR", "Title", "Status", "Date"}, rows)
+}