@shortlink-org/portolan 0.1.0

package/plugins/gen-markdown/coverage_test.go

@@ -0,0 +1,89 @@
+package main
+
+import (
+	"reflect"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// Every catalog field must be acknowledged when the mirror grows. Some are
+// printed, others are structural (ids, slugs and union discriminators), but a
+// new field may not disappear from generated documentation by default.
+var catalogCoverage = map[reflect.Type]string{
+	reflect.TypeOf(catalog.Catalog{}):          "generatedAt commit contexts defs flows adrs stores modules terms repos externals",
+	reflect.TypeOf(catalog.External{}):         "id slug name summary url provides",
+	reflect.TypeOf(catalog.RepoPin{}):          "repo commit",
+	reflect.TypeOf(catalog.BoundedContext{}):   "id slug name summary kind classification viewId services",
+	reflect.TypeOf(catalog.Service{}):          "id slug name repo path readme kind technologies provides consumes aggregates stores modules channels owners commands",
+	reflect.TypeOf(catalog.Command{}):          "runner name run doc body source",
+	reflect.TypeOf(catalog.RpcService{}):       "id methods source messages enums module",
+	reflect.TypeOf(catalog.RpcEnum{}):          "name doc values",
+	reflect.TypeOf(catalog.RpcEnumValue{}):     "name number doc",
+	reflect.TypeOf(catalog.RpcMethod{}):        "name doc request requestRef response responseRef streaming deprecated http soap",
+	reflect.TypeOf(catalog.HttpRoute{}):        "method path",
+	reflect.TypeOf(catalog.SoapRoute{}):        "action version style endpoint binding faults headers",
+	reflect.TypeOf(catalog.RpcMessage{}):       "name fields discriminator",
+	reflect.TypeOf(catalog.RpcDiscriminator{}): "property variants",
+	reflect.TypeOf(catalog.RpcVariant{}):       "value message",
+	reflect.TypeOf(catalog.RpcCall{}):          "id peer status source note module via",
+	reflect.TypeOf(catalog.EdgeVia{}):          "flow step",
+	reflect.TypeOf(catalog.ProtoModule{}):      "id slug name registry owner commit digest packages files deps source",
+	reflect.TypeOf(catalog.Aggregate{}):        "id slug name readme root entities valueObjects operations events enums lifecycle",
+	reflect.TypeOf(catalog.Enum{}):             "id slug name doc deprecated values",
+	reflect.TypeOf(catalog.EnumValue{}):        "name doc deprecated",
+	reflect.TypeOf(catalog.Lifecycle{}):        "states transitions",
+	reflect.TypeOf(catalog.Transition{}):       "from to on emits source",
+	reflect.TypeOf(catalog.Operation{}):        "id kind doc exposedBy",
+	reflect.TypeOf(catalog.Block{}):            "id slug name doc ref fields",
+	reflect.TypeOf(catalog.Event{}):            "id slug name versions consumers wire",
+	reflect.TypeOf(catalog.EventWire{}):        "name channel",
+	reflect.TypeOf(catalog.Channel{}):          "address kind title doc messages source",
+	reflect.TypeOf(catalog.ChannelMessage{}):   "name title doc direction",
+	reflect.TypeOf(catalog.EventConsumer{}):    "service status note via",
+	reflect.TypeOf(catalog.EventVersion{}):     "version doc source fields",
+	reflect.TypeOf(catalog.Field{}):            "name type doc ref",
+	reflect.TypeOf(catalog.TypeDef{}):          "fields",
+	reflect.TypeOf(catalog.Store{}):            "id slug name kind owner tables views keyspaces source",
+	reflect.TypeOf(catalog.RedisKeyspace{}):    "pattern operations ttl value source",
+	reflect.TypeOf(catalog.Table{}):            "id name doc columns indexes persists role",
+	reflect.TypeOf(catalog.Persists{}):         "aggregate block",
+	reflect.TypeOf(catalog.TableIndex{}):       "name columns unique",
+	reflect.TypeOf(catalog.Column{}):           "name type nullable pk fk from maps doc",
+	reflect.TypeOf(catalog.FK{}):               "table column onDelete",
+	reflect.TypeOf(catalog.View{}):             "id name doc materialized columns reads definition persists source",
+	reflect.TypeOf(catalog.Flow{}):             "id slug name summary source trigger entrypoint includes owner participants steps",
+	reflect.TypeOf(catalog.FlowTrigger{}):      "kind label confidence",
+	reflect.TypeOf(catalog.Participant{}):      "id kind context label",
+	reflect.TypeOf(catalog.Step{}):             "type id from to kind ref label status note line continuesAt reaches handoff",
+	reflect.TypeOf(catalog.FlowHandoff{}):      "kind transport channel message direction",
+	reflect.TypeOf(catalog.Parallel{}):         "type id title branches",
+	reflect.TypeOf(catalog.Alt{}):              "type id branches",
+	reflect.TypeOf(catalog.AltBranch{}):        "title steps terminal",
+	reflect.TypeOf(catalog.Loop{}):             "type id title steps",
+	reflect.TypeOf(catalog.AdrScope{}):         "kind context service",
+	reflect.TypeOf(catalog.Adr{}):              "id slug number title status date scope body note supersededBy supersedes relates source created revised",
+	reflect.TypeOf(catalog.AdrCommit{}):        "commit author date",
+	reflect.TypeOf(catalog.AdrRelates{}):       "services events flows",
+	reflect.TypeOf(catalog.Term{}):             "id slug context name definition source",
+}
+
+func TestCatalogFieldCoverageIsExplicit(t *testing.T) {
+	for typ, declared := range catalogCoverage {
+		want := strings.Fields(declared)
+		got := make([]string, 0, typ.NumField())
+		for i := 0; i < typ.NumField(); i++ {
+			name := strings.Split(typ.Field(i).Tag.Get("json"), ",")[0]
+			if name != "" && name != "-" {
+				got = append(got, name)
+			}
+		}
+		sort.Strings(want)
+		sort.Strings(got)
+		if strings.Join(want, " ") != strings.Join(got, " ") {
+			t.Errorf("%s coverage changed\nfields:  %s\ncovered: %s", typ.Name(), strings.Join(got, " "), strings.Join(want, " "))
+		}
+	}
+}

package/plugins/gen-markdown/describe.go

@@ -0,0 +1,19 @@
+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-markdown",
+		Summary: "Renders the merged catalog as a directory of markdown: a page per context, service, aggregate, store and flow.",
+		Phases:  []string{plugin.PhaseGenerate},
+		Options: optionsSchema,
+	}
+}

package/plugins/gen-markdown/describe_test.go

@@ -0,0 +1,11 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/shortlink-org/portolan/plugin/schematest"
+)
+
+func TestOptionsSchemaMatchesStruct(t *testing.T) {
+	schematest.Check(t, optionsSchema, Options{})
+}

package/plugins/gen-markdown/external.go

@@ -0,0 +1,71 @@
+package main
+
+import (
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// renderExternals writes one page per system outside the estate. The page
+// says what the catalog may claim about it - what it answers on, read from
+// the vendored copy of its document, and who of ours calls it - and nothing
+// the estate would have to own the far end to know.
+func (s *site) renderExternals() {
+	for i := range s.cat.Externals {
+		s.renderExternal(&s.cat.Externals[i])
+	}
+}
+
+func (s *site) renderExternal(ext *catalog.External) {
+	self := s.pathOf[ext.ID]
+
+	var b strings.Builder
+	b.WriteString("# " + orDefault(ext.Name, ext.ID) + "\n\n")
+	b.WriteString(s.stamp() + "\n")
+
+	rows := [][]string{
+		{"Id", code(ext.ID)},
+		{"Where", "outside the estate"},
+	}
+	if ext.URL != "" {
+		rows = append(rows, []string{"Documented at", "<" + ext.URL + ">"})
+	}
+	b.WriteString(defList(rows))
+
+	if ext.Summary != "" {
+		b.WriteString("\n" + ext.Summary + "\n")
+	}
+
+	section(&b, "Provides", s.providesBlock(self, ext.Provides, nil))
+	section(&b, "Called by", s.calledByTable(self, ext.ID))
+
+	s.b.file(self, b.String())
+}
+
+// calledByTable is every call in the catalog that lands on the external. The
+// service pages list their own calls outward; this is the one place the
+// callers of a third party stand together.
+func (s *site) calledByTable(from, externalID string) string {
+	var rows [][]string
+	for i := range s.cat.Contexts {
+		ctx := &s.cat.Contexts[i]
+		for j := range ctx.Services {
+			svc := &ctx.Services[j]
+			for k := range svc.Consumes {
+				call := &svc.Consumes[k]
+				if call.Peer != externalID {
+					continue
+				}
+				rows = append(rows, []string{
+					s.ref(from, svc.ID, svc.Name),
+					code(call.ID),
+					string(call.Status),
+					s.source(from, call.Source, svc),
+					s.viaRef(from, call.Via),
+				})
+			}
+		}
+	}
+
+	return table([]string{"Service", "Call", "Status", "Source", "Via"}, rows)
+}

package/plugins/gen-markdown/flow.go

@@ -0,0 +1,277 @@
+package main
+
+import (
+	"path"
+	"strconv"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	flowmermaid "github.com/shortlink-org/portolan/render/mermaid"
+)
+
+func (s *site) renderFlows() {
+	if len(s.cat.Flows) == 0 {
+		return
+	}
+
+	const self = "flows/README.md"
+
+	var b strings.Builder
+	b.WriteString("# Flows\n\n")
+	b.WriteString(s.stamp() + "\n")
+
+	rows := 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)
+		}
+		rows = append(rows, []string{
+			s.ref(self, flow.ID, flow.Name),
+			owner,
+			firstLine(flow.Summary),
+		})
+	}
+	b.WriteString(table([]string{"Flow", "Owner", "Summary"}, rows))
+
+	s.b.file(self, b.String())
+
+	for i := range s.cat.Flows {
+		s.renderFlow(&s.cat.Flows[i])
+	}
+}
+
+func (s *site) renderFlow(flow *catalog.Flow) {
+	self := s.pathOf[flow.ID]
+
+	var b strings.Builder
+	b.WriteString("# " + flow.Name + "\n\n")
+	b.WriteString(s.stamp() + "\n")
+
+	meta := [][]string{
+		{"Id", code(flow.ID)},
+	}
+	if flow.Owner != "" {
+		meta = append(meta, []string{"Owner", s.ref(self, flow.Owner, flow.Owner)})
+	}
+	if flow.Trigger != nil {
+		trigger := code(flow.Trigger.Kind)
+		if flow.Trigger.Label != "" {
+			trigger += " · " + flow.Trigger.Label
+		}
+		meta = append(meta,
+			[]string{"Trigger", trigger},
+			[]string{"Root confidence", flow.Trigger.Confidence},
+		)
+	}
+	// Source is the file the flow was read out of, which is the only thing a
+	// reader can go and check for themselves.
+	if flow.Source != "" {
+		meta = append(meta, []string{"Source", s.source(self, flow.Source, s.serviceForSource(flow.Source))})
+	}
+	b.WriteString(defList(meta))
+
+	if flow.Summary != "" {
+		b.WriteString("\n" + flow.Summary + "\n")
+	}
+
+	participants := make([][]string, 0, len(flow.Participants))
+	for i := range flow.Participants {
+		p := &flow.Participants[i]
+		context := "—"
+		if p.Context != nil {
+			context = s.ref(self, *p.Context, *p.Context)
+		}
+		participants = append(participants, []string{code(p.ID), string(p.Kind), context, p.Label})
+	}
+	section(&b, "Participants", table([]string{"Participant", "Kind", "Context", "Label"}, participants))
+
+	section(&b, "Sequence", fence("mermaid", flowmermaid.Sequence(flow, s.labelWithAnswer)))
+
+	counter := 0
+	section(&b, "Steps", s.stepList(self, flow, flow.Steps, &counter))
+
+	s.b.file(self, b.String())
+}
+
+// stepList is the same walk again, in prose. The diagram shows the shape and
+// the list carries what will not fit on an arrow: where the step was read
+// from, how far it is trusted, and what it refers to.
+//
+// Branches are wrapped in block quotes rather than indented. Four spaces of
+// indentation is a code block in markdown, and three is a continuation of
+// whatever list came before - a quote is the one nesting that means nesting.
+func (s *site) stepList(self string, flow *catalog.Flow, nodes catalog.FlowNodes, counter *int) string {
+	var b strings.Builder
+
+	for _, node := range nodes {
+		switch n := node.(type) {
+		case *catalog.Step:
+			*counter++
+			b.WriteString("<a id=\"step-" + anchorID(n.ID) + "\"></a>\n")
+
+			arrow := " → "
+			if n.From == n.To {
+				arrow = " ↺ "
+			}
+			b.WriteString(strconv.Itoa(*counter) + ". **" + n.From + "**" + arrow + "**" + n.To + "** — " + s.labelWithAnswer(n) + "\n")
+
+			var notes []string
+			if n.Ref != "" {
+				notes = append(notes, s.stepRef(self, n))
+			}
+			if n.Status != catalog.StatusVerified {
+				notes = append(notes, "status: "+string(n.Status))
+			}
+			if n.Line != "" {
+				location := n.Line
+				if flow.Source != "" && path.Dir(sourceFile(n.Line)) == "." {
+					location = path.Join(path.Dir(sourceFile(flow.Source)), n.Line)
+				}
+				notes = append(notes, s.source(self, location, s.serviceForSource(flow.Source)))
+			}
+			if n.Note != "" {
+				notes = append(notes, n.Note)
+			}
+			if len(notes) > 0 {
+				// Three spaces line the continuation up under the "1. " marker.
+				b.WriteString("   " + strings.Join(notes, " · ") + "\n")
+			}
+
+			if n.Status == catalog.StatusUnresolved {
+				s.b.warn(flow.ID, "%s step %q is unresolved: %s", flow.ID, n.ID, stepLabel(n))
+			}
+
+		case *catalog.Parallel:
+			var inner strings.Builder
+			inner.WriteString("**In parallel** — " + orDefault(n.Title, "branches that do not wait for each other") + "\n")
+			for i, branch := range n.Branches {
+				inner.WriteString("\n*Branch " + strconv.Itoa(i+1) + "*\n\n")
+				inner.WriteString(s.stepList(self, flow, branch, counter))
+			}
+			b.WriteString("\n" + quote(inner.String()) + "\n")
+
+		case *catalog.Alt:
+			var inner strings.Builder
+			// "One of" rather than "if": exactly one branch runs, and a reader
+			// who takes the branches for a sequence reads the flow backwards.
+			inner.WriteString("**One of**\n")
+			for _, branch := range n.Branches {
+				title := branch.Title
+				if branch.Terminal {
+					title += " — *ends the flow*"
+				}
+				inner.WriteString("\n*" + title + "*\n\n")
+				inner.WriteString(s.stepList(self, flow, branch.Steps, counter))
+			}
+			b.WriteString("\n" + quote(inner.String()) + "\n")
+
+		case *catalog.Loop:
+			var inner strings.Builder
+			inner.WriteString("**Repeats** — " + n.Title + "\n\n")
+			inner.WriteString(s.stepList(self, flow, n.Steps, counter))
+			b.WriteString("\n" + quote(inner.String()) + "\n")
+		}
+	}
+
+	return b.String()
+}
+
+// quote wraps a block so it nests visibly, at any depth, without markdown
+// mistaking the indentation for something else.
+func quote(block string) string {
+	lines := strings.Split(strings.TrimRight(block, "\n"), "\n")
+	for i, line := range lines {
+		if line == "" {
+			lines[i] = ">"
+
+			continue
+		}
+		lines[i] = "> " + line
+	}
+
+	return strings.Join(lines, "\n") + "\n"
+}
+
+// stepRef links a step to what it refers to. An event id resolves to the
+// aggregate page that publishes it; anything else is shown as written.
+func (s *site) stepRef(self string, step *catalog.Step) string {
+	if step.Kind == catalog.StepEvent {
+		if _, ok := s.eventPage[step.Ref]; ok {
+			return s.eventRef(self, step.Ref, step.Ref)
+		}
+		if step.Status != catalog.StatusUnresolved {
+			s.b.warn(step.Ref, "step %q refers to event %q, which no service in this catalog publishes", step.ID, step.Ref)
+		}
+	}
+
+	return code(step.Ref)
+}
+
+func stepLabel(step *catalog.Step) string {
+	switch {
+	case step.Label != "":
+		return step.Label
+	case step.Ref != "":
+		return step.Ref
+	default:
+		return string(step.Kind)
+	}
+}
+
+// mermaidText makes a label safe on a mermaid line. A newline ends the
+// statement, a semicolon ends it too, and a bare # opens an entity code.
+func mermaidText(s string) string {
+	return flowmermaid.Text(s)
+}
+
+func orDefault(s, fallback string) string {
+	if strings.TrimSpace(s) == "" {
+		return fallback
+	}
+
+	return s
+}
+
+// labelWithAnswer is the step's label, and what comes back when a contract
+// says so.
+func (s *site) labelWithAnswer(step *catalog.Step) string {
+	if answer := s.answer(step); answer != "" {
+		return stepLabel(step) + " → " + answer
+	}
+
+	return stepLabel(step)
+}
+
+// answer is what the far end of an rpc hands back, as the contract names it.
+// The mirror of src/flow/answers.ts, and the prose is there.
+//
+// Only an rpc has one: a call lands inside a service, which no interface
+// describes, and an event is a publication - a reply drawn to one would be a
+// lie about the bus.
+func (s *site) answer(step *catalog.Step) string {
+	if step.Kind != catalog.StepRPC {
+		return ""
+	}
+
+	// Outgoing: the step names the call, and a call id is "<interface>/<method>".
+	if step.Ref != "" {
+		return s.methodOf[step.Ref].Response
+	}
+
+	// Incoming: somebody called this service, and the label is the operation.
+	service, ok := s.services[step.To]
+	if !ok || step.Label == "" {
+		return ""
+	}
+	for i := range service.Provides {
+		for j := range service.Provides[i].Methods {
+			if service.Provides[i].Methods[j].Name == step.Label {
+				return service.Provides[i].Methods[j].Response
+			}
+		}
+	}
+
+	return ""
+}

package/plugins/gen-markdown/glossary.go

@@ -0,0 +1,76 @@
+package main
+
+// The vocabulary of one context, as a page of its own.
+//
+// It is not folded into the context's README for the same reason the source
+// is its own file: the README says what the services do, the glossary says
+// what the words in that sentence mean, and a reader consults them at
+// different moments. It is also the page a model reading this estate wants
+// FIRST - every other page is written in these words.
+//
+// Nothing here is derived. A definition is the author's sentence, carried
+// through as written, and the only thing this file decides is the order it is
+// read in and where the words came from.
+
+import (
+	"sort"
+	"strconv"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+const glossaryFile = "glossary.md"
+
+// glossaryPath is where a context's vocabulary is documented: beside its
+// README, so the two sit together in the tree the way they sit together in
+// the repository the terms were read from.
+func (s *site) glossaryPath(ctx *catalog.BoundedContext) string {
+	return ctx.Slug + "/" + glossaryFile
+}
+
+func (s *site) renderGlossary(ctx *catalog.BoundedContext) {
+	terms := s.termsOf[ctx.ID]
+	if len(terms) == 0 {
+		return
+	}
+	self := s.glossaryPath(ctx)
+
+	var b strings.Builder
+	b.WriteString("# Glossary — " + ctx.Name + "\n\n")
+	b.WriteString(s.stamp() + "\n")
+	b.WriteString(defList([][]string{
+		{"Context", s.ref(self, ctx.ID, ctx.Name)},
+		{"Terms", strconv.Itoa(len(terms))},
+		{"Read from", strings.Join(s.termSources(self, terms), ", ")},
+	}))
+
+	b.WriteString("\nOne meaning per word inside this context, as the glossary" +
+		" beside the code states it.\n")
+
+	// A list rather than a table. A definition is a sentence or two of prose,
+	// and a table cell is where a sentence goes to be truncated - the same
+	// reason the source file is prose. A list also diffs by the term.
+	var out strings.Builder
+	for _, term := range terms {
+		out.WriteString("- **" + term.Name + "** — " + term.Definition + "\n")
+	}
+	section(&b, "Terms", out.String())
+
+	s.b.file(self, b.String())
+}
+
+func (s *site) termSources(from string, terms []*catalog.Term) []string {
+	seen := map[string]bool{}
+	var out []string
+	for _, term := range terms {
+		file := sourceFile(term.Source)
+		if file == "" || seen[file] {
+			continue
+		}
+		seen[file] = true
+		out = append(out, s.source(from, file, s.serviceForSource(file)))
+	}
+	sort.Strings(out)
+	return out
+}

package/plugins/gen-markdown/glossary_test.go

@@ -0,0 +1,148 @@
+package main
+
+// What the glossary page promises, said once here rather than read out of the
+// golden tree: the golden proves the bytes, these prove the intent.
+
+import (
+	"encoding/json"
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+func rendered(t *testing.T) map[string]string {
+	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)
+	}
+
+	out := map[string]string{}
+	for _, file := range render(plugin.Request{Catalog: cat}, Options{Title: "Golden estate"}).Files {
+		out[file.Name] = file.Contents
+	}
+
+	return out
+}
+
+func page(t *testing.T, name string) string {
+	t.Helper()
+
+	pages := rendered(t)
+	body, ok := pages[name]
+	if !ok {
+		t.Fatalf("no page %s", name)
+	}
+
+	return body
+}
+
+// A page of its own, beside the context's README: the README says what the
+// services do, the glossary says what the words in that sentence mean.
+func TestGlossaryIsItsOwnPage(t *testing.T) {
+	body := page(t, "billing/glossary.md")
+
+	if !strings.HasPrefix(body, "# Glossary — Billing\n") {
+		t.Errorf("the page opens with %q", strings.SplitN(body, "\n", 2)[0])
+	}
+	for _, want := range []string{
+		"**Invoice** — What a customer is asked to pay",
+		"**Dunning** — Asking again, on a schedule",
+	} {
+		if !strings.Contains(body, want) {
+			t.Errorf("no %q in:\n%s", want, body)
+		}
+	}
+}
+
+// Alphabetical, whatever order the sources merged in. A glossary is looked up,
+// not read through, and catalog order is nobody's index.
+func TestTermsAreAlphabetical(t *testing.T) {
+	body := page(t, "billing/glossary.md")
+
+	dunning := strings.Index(body, "**Dunning**")
+	invoice := strings.Index(body, "**Invoice**")
+	if dunning < 0 || invoice < 0 || dunning > invoice {
+		t.Errorf("Dunning at %d, Invoice at %d", dunning, invoice)
+	}
+}
+
+// The file the words were read from, named once on the page rather than once
+// per term: the reader who disagrees with a definition edits that file.
+func TestThePageNamesWhereTheWordsWereWritten(t *testing.T) {
+	if body := page(t, "billing/glossary.md"); !strings.Contains(body, "examples/billing/GLOSSARY.md") {
+		t.Errorf("the page does not say where it was read from:\n%s", body)
+	}
+}
+
+func TestTheContextPageLinksItsGlossary(t *testing.T) {
+	if body := page(t, "billing/README.md"); !strings.Contains(body, "[Glossary](glossary.md)") {
+		t.Errorf("the context page does not link the glossary:\n%s", body)
+	}
+}
+
+func TestServiceReadmeLinksUseGeneratedAdrAndGlossaryPages(t *testing.T) {
+	body := page(t, "billing/invoices/README.md")
+
+	for _, want := range []string{
+		"[GLOSSARY.md](../glossary.md)",
+		"[billing.0001](../../adr/billing.0001.md)",
+	} {
+		if !strings.Contains(body, want) {
+			t.Errorf("the service README does not rewrite %q:\n%s", want, body)
+		}
+	}
+	if strings.Contains(body, "](GLOSSARY.md)") || strings.Contains(body, "](../../docs/adr/0001.md)") {
+		t.Errorf("the copied source links survived unchanged:\n%s", body)
+	}
+}
+
+// Straight after the contexts, before the pages that are written in these
+// words. A model reading the estate cold has the same problem a person has.
+func TestLlmsListsTheGlossaries(t *testing.T) {
+	body := page(t, "llms.txt")
+
+	if !strings.Contains(body, "## Glossaries") {
+		t.Fatalf("no Glossaries section:\n%s", body)
+	}
+	if !strings.Contains(body, "[Glossary of Billing](billing/glossary.md): 2 terms. Dunning, Invoice") {
+		t.Errorf("the entry is not what it should be:\n%s", body)
+	}
+	if strings.Index(body, "## Glossaries") > strings.Index(body, "## Services") {
+		t.Error("the glossaries sit after the services")
+	}
+}
+
+// An estate that has written no glossary renders exactly as it did before
+// there was one to write.
+func TestAContextWithNoGlossaryGetsNoPage(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)
+	}
+	cat.Terms = nil
+
+	for _, file := range render(plugin.Request{Catalog: cat}, Options{}).Files {
+		if strings.HasSuffix(file.Name, glossaryFile) {
+			t.Errorf("rendered %s for a catalog with no terms", file.Name)
+		}
+		if file.Name == "llms.txt" && strings.Contains(file.Contents, "Glossaries") {
+			t.Error("llms.txt has a Glossaries section with no glossaries")
+		}
+		if file.Name == "billing/README.md" && strings.Contains(file.Contents, "## Language") {
+			t.Error("the context page has a Language section with no terms")
+		}
+	}
+}