@shortlink-org/portolan 0.1.0

package/plugins/extract-flows/parse_test.go

@@ -0,0 +1,204 @@
+package main
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+const sample = `# Order accepted
+owner: shop
+source: services/oms/test/integration/order_accepted_test.go
+
+The narrow slice one integration test pins end to end: an order commits
+with its outbox row.
+
+Every hop here is asserted.
+
+## Participants
+- oms-db: store in shop "oms-db (postgres)"
+- psp-gateway: external "psp-gateway (external)"
+- customer: actor
+
+## Steps
+// the request
+customer -> shop.oms: rpc PlaceOrder [verified] @internal/oms/http/orders.go:40
+shop.oms -> oms-db: insertOrderAndOutboxRow [verified] @internal/oms/adapter/postgres/order_repo.go:141 #a1
+  > The order row and the OrderPlaced outbox row commit in one
+  > transaction.
+shop.oms -> bus: event shop.oms.order.OrderPlaced [verified]
+payments.ledger -> psp-gateway: rpc psp.v2.Charges/Create as "Charges.Create (auth only)" [unresolved] @internal/ledger/adapter/psp/client.go:64
+
+alt score below 40 #alt-risk
+  bus -> payments.ledger: event shop.oms.order.OrderPlaced
+else score at or above 40
+  shop.oms -> bus: event shop.oms.order.OrderCancelled
+  stop
+else
+end
+
+par OrderPlaced fan-out #par-placed
+  bus -> payments.ledger: event shop.oms.order.OrderPlaced
+and
+  bus -> delivery.core: event shop.oms.order.OrderPlaced
+end
+
+loop outbox relay, every 200 ms until the batch is empty
+  shop.oms -> oms-db: SELECT ... FOR UPDATE SKIP LOCKED
+end
+`
+
+func parsed(t *testing.T, src string) catalog.Flow {
+	t.Helper()
+	flow, errs := parseFlow("data/flows/order-accepted.flow.md", src)
+	if len(errs) > 0 {
+		t.Fatalf("errors: %s", strings.Join(errs, "\n"))
+	}
+
+	return flow
+}
+
+func TestTheHeadIsReadIntoTheFlow(t *testing.T) {
+	flow := parsed(t, sample)
+	if flow.ID != "flow.order-accepted" || flow.Slug != "order-accepted" || flow.Name != "Order accepted" || flow.Owner != "shop" {
+		t.Errorf("flow = %+v", flow)
+	}
+	if flow.Source != "services/oms/test/integration/order_accepted_test.go" {
+		t.Errorf("source = %q", flow.Source)
+	}
+	want := "The narrow slice one integration test pins end to end: an order commits with its outbox row.\n\nEvery hop here is asserted."
+	if flow.Summary != want {
+		t.Errorf("summary = %q", flow.Summary)
+	}
+}
+
+// Declared lanes come first, in the order written; the ones a step brings in
+// - services by their id, the bus by its name - follow in order of first use.
+func TestLanesAreDeclaredOrInferred(t *testing.T) {
+	flow := parsed(t, sample)
+	var ids []string
+	for _, p := range flow.Participants {
+		ids = append(ids, p.ID+"/"+string(p.Kind))
+	}
+	want := "oms-db/store psp-gateway/external customer/actor shop.oms/service bus/broker payments.ledger/service delivery.core/service"
+	if strings.Join(ids, " ") != want {
+		t.Errorf("lanes = %s", strings.Join(ids, " "))
+	}
+	if store := flow.Participants[0]; store.Label != "oms-db (postgres)" || store.Context == nil || *store.Context != "shop" {
+		t.Errorf("store lane = %+v", store)
+	}
+	if oms := flow.Participants[3]; oms.Context == nil || *oms.Context != "shop" {
+		t.Errorf("service lane = %+v", oms)
+	}
+}
+
+func TestAHopCarriesEverythingWrittenAfterIt(t *testing.T) {
+	flow := parsed(t, sample)
+	first := flow.Steps[0].(*catalog.Step)
+	if first.ID != "s1" || first.Kind != catalog.StepRPC || first.Label != "PlaceOrder" || first.Ref != "" || first.Status != catalog.StatusVerified || first.Line != "internal/oms/http/orders.go:40" {
+		t.Errorf("first = %+v", first)
+	}
+	second := flow.Steps[1].(*catalog.Step)
+	if second.ID != "a1" || second.Kind != catalog.StepCall || second.Label != "insertOrderAndOutboxRow" {
+		t.Errorf("second = %+v", second)
+	}
+	if second.Note != "The order row and the OrderPlaced outbox row commit in one transaction." {
+		t.Errorf("note = %q", second.Note)
+	}
+	third := flow.Steps[2].(*catalog.Step)
+	if third.ID != "s2" || third.Ref != "shop.oms.order.OrderPlaced" || third.Label != "OrderPlaced" || third.From != "shop.oms" || third.To != "bus" {
+		t.Errorf("third = %+v; an explicit id does not use up a number", third)
+	}
+	fourth := flow.Steps[3].(*catalog.Step)
+	if fourth.Ref != "psp.v2.Charges/Create" || fourth.Label != "Charges.Create (auth only)" || fourth.Status != catalog.StatusUnresolved {
+		t.Errorf("fourth = %+v", fourth)
+	}
+}
+
+func TestFramesCloseWithEnd(t *testing.T) {
+	flow := parsed(t, sample)
+	alt, ok := flow.Steps[4].(*catalog.Alt)
+	if !ok || alt.ID != "alt-risk" || len(alt.Branches) != 3 {
+		t.Fatalf("alt = %+v", flow.Steps[4])
+	}
+	if alt.Branches[0].Title != "score below 40" || alt.Branches[0].Terminal || len(alt.Branches[0].Steps) != 1 {
+		t.Errorf("branch 0 = %+v", alt.Branches[0])
+	}
+	if alt.Branches[1].Title != "score at or above 40" || !alt.Branches[1].Terminal {
+		t.Errorf("branch 1 = %+v; `stop` makes it terminal", alt.Branches[1])
+	}
+	if alt.Branches[2].Title != "otherwise" || len(alt.Branches[2].Steps) != 0 {
+		t.Errorf("branch 2 = %+v; a bare else is otherwise, and empty is allowed", alt.Branches[2])
+	}
+
+	par, ok := flow.Steps[5].(*catalog.Parallel)
+	if !ok || par.ID != "par-placed" || par.Title != "OrderPlaced fan-out" || len(par.Branches) != 2 {
+		t.Fatalf("par = %+v", flow.Steps[5])
+	}
+	loop, ok := flow.Steps[6].(*catalog.Loop)
+	if !ok || loop.ID != "loop8" || !strings.HasPrefix(loop.Title, "outbox relay") || len(loop.Steps) != 1 {
+		t.Fatalf("loop = %+v", flow.Steps[6])
+	}
+}
+
+// An rpc with no interface behind it - a webhook arriving on a route - keeps
+// the route as its label and has no ref to resolve.
+func TestARouteIsALabelNotARef(t *testing.T) {
+	src := "# Webhook\nowner: payments\n\n## Participants\n- psp-gateway: external\n\n## Steps\npsp-gateway -> payments.ledger: rpc POST /webhooks/psp/v2 [verified]\npayments.ledger -> shop.oms: rpc shop.v1.Orders/GetOrder\n"
+	flow, errs := parseFlow("w.flow.md", src)
+	if len(errs) > 0 {
+		t.Fatal(errs)
+	}
+	first := flow.Steps[0].(*catalog.Step)
+	if first.Ref != "" || first.Label != "POST /webhooks/psp/v2" {
+		t.Errorf("first = %+v", first)
+	}
+	second := flow.Steps[1].(*catalog.Step)
+	if second.Ref != "shop.v1.Orders/GetOrder" || second.Label != "GetOrder" {
+		t.Errorf("second = %+v", second)
+	}
+}
+
+func TestTheFileIsTheSourceWhenNoneIsNamed(t *testing.T) {
+	src := "# Login\nowner: auth\n\n## Steps\nclient -> auth.auth: rpc login\n"
+	flow, errs := parseFlow("data/flows/login.flow.md", src)
+	if len(errs) > 0 {
+		t.Fatal(errs)
+	}
+	if flow.Source != "data/flows/login.flow.md" || flow.Slug != "login" {
+		t.Errorf("flow = %+v", flow)
+	}
+	if flow.Participants[0].Kind != catalog.ParticipantActor || flow.Participants[0].ID != "client" {
+		t.Errorf("client is an actor by name: %+v", flow.Participants)
+	}
+}
+
+// Every mistake is named with its line, and none of them is silent.
+func TestMistakesAreNamedWithTheirLine(t *testing.T) {
+	cases := []struct{ src, want string }{
+		{"# X\nowner: a\n\n## Steps\na.b -> c.d: hop\nalt when\n  a.b -> c.d: x\n", "alt is never closed"},
+		{"# X\nowner: a\n\n## Steps\nalt when\n  a.b -> c.d: x\nend\n", "needs an `else`"},
+		{"# X\nowner: a\n\n## Steps\nalt when\n  a.b -> c.d: x\n  stop\nelse\n  a.b -> c.d: y\n  stop\nend\n", "every branch of this alt stops"},
+		{"# X\nowner: a\n\n## Steps\na.b -> mystery: hop\n", `"mystery" is not declared`},
+		{"# X\nowner: a\n\n## Steps\na.b -> c.d: hop [maybe]\n", "not one of verified"},
+		{"# X\nowner: a\n\n## Steps\na.b -> c.d: hop #s1\na.b -> c.d: hop #s1\n", "used twice"},
+		{"# X\nowner: a\n\n## Steps\n> orphan\n", "has to follow the step"},
+		{"# X\n\n## Steps\na.b -> c.d: hop\n", "no owner"},
+		{"# X\nowner: a\n\n## Steps\nloop\n  a.b -> c.d: hop\nend\n", "loop needs a title"},
+		{"# X\nowner: a\n\n## Steps\nalt when\n  a.b -> c.d: x\n  stop\n  a.b -> c.d: y\nelse\nend\n", "nothing runs after `stop`"},
+		{"# X\nowner: a\n\n## Steps\na.b -> c.d: hop [verified] wat\n", "cannot read"},
+	}
+	for _, c := range cases {
+		_, errs := parseFlow("f.flow.md", c.src)
+		if len(errs) == 0 {
+			t.Errorf("%q: no error, want %q", c.src, c.want)
+
+			continue
+		}
+		joined := strings.Join(errs, "\n")
+		if !strings.Contains(joined, c.want) || !strings.Contains(joined, "f.flow.md:") {
+			t.Errorf("%q: errors = %q, want %q with a line", c.src, joined, c.want)
+		}
+	}
+}

package/plugins/extract-glossary/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:    "extract-glossary",
+		Summary: "Reads a context's GLOSSARY.md - one paragraph per term, what it is and what it is not - into a catalog fragment.",
+		Phases:  []string{plugin.PhaseExtract},
+		Options: optionsSchema,
+	}
+}

package/plugins/extract-glossary/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/extract-glossary/extract.go

@@ -0,0 +1,115 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"regexp"
+	"sort"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+var contextSlug = regexp.MustCompile(`^[a-z][a-z0-9-]*$`)
+
+// extract reads every glossary the options name and answers with one fragment
+// holding their terms.
+//
+// A file that cannot be parsed fails the whole run rather than being left out:
+// a fragment silently missing half a vocabulary is a site where a word simply
+// has no meaning, with nothing on the page to say a file was skipped and why.
+// What is merely incomplete - an entry that never says what the term is not,
+// a glossary that drifted out of alphabetical order - comes back as warnings,
+// which the host prints and nobody has to act on today.
+func extract(in plugin.Input, opts Options) (plugin.Response, error) {
+	b := &plugin.Builder{}
+
+	context := opts.Context
+	if context == "" {
+		context = filepath.Base(in.Root)
+	}
+	if !contextSlug.MatchString(context) {
+		return plugin.Response{}, errors.New(context + " is not a context slug: a term's id is the context and the term, so the context has to be one word the way the estate spells it")
+	}
+
+	patterns := opts.Files
+	if len(patterns) == 0 {
+		patterns = []string{"GLOSSARY.md"}
+	}
+	var files []string
+	seen := map[string]bool{}
+	for _, pattern := range patterns {
+		matches, err := filepath.Glob(filepath.Join(in.Root, pattern))
+		if err != nil {
+			return plugin.Response{}, err
+		}
+		for _, match := range matches {
+			if !seen[match] {
+				seen[match] = true
+				files = append(files, match)
+			}
+		}
+	}
+	sort.Strings(files)
+	if len(files) == 0 {
+		b.Warn(in.Root, "no glossary matched "+strings.Join(patterns, ", ")+"; the fragment holds no terms")
+	}
+
+	terms := []catalog.Term{}
+	ids := map[string]string{}
+	var problems []string
+	for _, file := range files {
+		src, err := os.ReadFile(file)
+		if err != nil {
+			return plugin.Response{}, err
+		}
+		rel := filepath.ToSlash(file)
+		parsed, warns, errs := parseGlossary(rel, context, string(src))
+		if len(errs) > 0 {
+			problems = append(problems, errs...)
+
+			continue
+		}
+		for _, warn := range warns {
+			b.Warn(rel, strings.TrimPrefix(warn, rel+": "))
+		}
+		for _, term := range parsed {
+			// Two files in one context defining one word is the failure the
+			// glossary exists to prevent, said in the glossaries themselves.
+			if other, taken := ids[term.ID]; taken {
+				problems = append(problems, term.Source+": "+term.Name+" is already defined in "+other)
+
+				continue
+			}
+			ids[term.ID] = term.Source
+			terms = append(terms, term)
+		}
+	}
+	if len(problems) > 0 {
+		return plugin.Response{}, errors.New(strings.Join(problems, "\n"))
+	}
+
+	fragment := catalog.Catalog{
+		GeneratedAt: in.GeneratedAt,
+		Commit:      in.Commit,
+		Contexts:    []catalog.BoundedContext{},
+		Defs:        map[string]catalog.TypeDef{},
+		Flows:       []catalog.Flow{},
+		Adrs:        []catalog.Adr{},
+		Terms:       terms,
+	}
+	encoded, err := json.MarshalIndent(fragment, "", "  ")
+	if err != nil {
+		return plugin.Response{}, err
+	}
+	out := opts.Out
+	if out == "" {
+		out = "glossary.json"
+	}
+	b.File(out, string(encoded)+"\n")
+
+	return b.Response(), nil
+}

package/plugins/extract-glossary/extract_test.go

@@ -0,0 +1,220 @@
+package main
+
+// The mapping: glossaries in a tree, a catalog fragment out.
+//
+// Shaped like plugins/extract-adr/extract_test.go, which is the house style
+// for an extractor test - one behaviour per test, and a whole-fragment golden
+// underneath so an unintended field change is a diff rather than an assertion
+// nobody thought to write.
+
+import (
+	"encoding/json"
+	"flag"
+	"os"
+	"strconv"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+var update = flag.Bool("update", false, "rewrite the golden fragment instead of comparing against it")
+
+const goldenPath = "testdata/golden/glossary.json"
+
+func input(root string) plugin.Input {
+	// The stamp comes from the host, which derives it from git. A plugin that
+	// read a clock would write a different file every run.
+	return plugin.Input{
+		Root:        root,
+		Commit:      "abc1234",
+		GeneratedAt: "2024-01-01T00:00:00Z",
+	}
+}
+
+func response(t *testing.T) plugin.Response {
+	t.Helper()
+
+	resp, err := extract(input("testdata/estate"), Options{Context: "auth"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	return resp
+}
+
+func fragment(t *testing.T) catalog.Catalog {
+	t.Helper()
+
+	var cat catalog.Catalog
+	if err := json.Unmarshal([]byte(response(t).Files[0].Contents), &cat); err != nil {
+		t.Fatal(err)
+	}
+
+	return cat
+}
+
+func TestEveryTermInTheTreeIsRead(t *testing.T) {
+	var ids []string
+	for _, term := range fragment(t).Terms {
+		ids = append(ids, term.ID)
+	}
+	if strings.Join(ids, " ") != "auth.email-address auth.session auth.version" {
+		t.Errorf("ids = %v", ids)
+	}
+}
+
+// The file sits beside a service and the words in it belong to a context, so
+// the directory is the wrong answer whenever a context holds more than one
+// service - which is the case this option exists for.
+func TestTheContextIsAskedForRatherThanDerived(t *testing.T) {
+	resp, err := extract(input("testdata/estate"), Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var cat catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &cat); err != nil {
+		t.Fatal(err)
+	}
+	if got := cat.Terms[0].ID; got != "estate.email-address" {
+		t.Errorf("without the option the id is %q, want the directory's name", got)
+	}
+	if got := fragment(t).Terms[0].ID; got != "auth.email-address" {
+		t.Errorf("with the option the id is %q", got)
+	}
+}
+
+// A context that is not a slug would build ids nothing else in the estate can
+// match, and the term would simply never be found again.
+func TestAContextThatIsNotASlugIsRefused(t *testing.T) {
+	_, err := extract(input("testdata/estate"), Options{Context: "shop.oms"})
+	if err == nil {
+		t.Fatal("a dotted context produced a fragment")
+	}
+	if !strings.Contains(err.Error(), "is not a context slug") {
+		t.Errorf("refusal is %q", err)
+	}
+}
+
+// The fragment is one source among several, so it carries the empty lists of
+// everything it says nothing about rather than leaving the merge to guess.
+func TestTheFragmentSaysNothingItDidNotRead(t *testing.T) {
+	cat := fragment(t)
+	if len(cat.Contexts) != 0 || len(cat.Flows) != 0 || len(cat.Defs) != 0 || len(cat.Adrs) != 0 {
+		t.Errorf("the fragment claims more than its terms: %+v", cat)
+	}
+	if cat.Commit != "abc1234" || cat.GeneratedAt != "2024-01-01T00:00:00Z" {
+		t.Errorf("stamp = %q %q", cat.Commit, cat.GeneratedAt)
+	}
+}
+
+func TestTheFileIsNamedByTheOptions(t *testing.T) {
+	resp, err := extract(input("testdata/estate"), Options{Context: "auth", Out: "words.json"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.Files[0].Name != "words.json" {
+		t.Errorf("name = %q", resp.Files[0].Name)
+	}
+	if response(t).Files[0].Name != "glossary.json" {
+		t.Errorf("the default is not glossary.json")
+	}
+}
+
+// A root with no glossary is worth saying out loud. A step pointed at the
+// wrong directory answers with an empty fragment either way, and the warning
+// is the only thing that tells the two apart.
+func TestARootWithNoGlossaryWarns(t *testing.T) {
+	resp, err := extract(input("testdata"), Options{Context: "auth"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !warnedAbout(resp, "no glossary matched") {
+		t.Errorf("diagnostics = %+v", resp.Warnings())
+	}
+}
+
+// Every rule the format has is checked here, where the file that broke it can
+// be named. A fragment written half-valid is a word with no meaning on a page
+// later, with the reason a long way from its cause.
+func TestABrokenGlossaryIsRefusedWholeRatherThanWrittenHalf(t *testing.T) {
+	resp, err := extract(input("testdata/broken"), Options{Context: "shop"})
+	if err == nil {
+		t.Fatal("the broken tree produced a fragment")
+	}
+	if len(resp.Files) != 0 {
+		t.Errorf("files were named anyway: %+v", resp.Files)
+	}
+	if !strings.Contains(err.Error(), "prose") {
+		t.Errorf("refusal is %q", err)
+	}
+}
+
+// One context, one vocabulary: two files defining the same word is the failure
+// the glossary is written to prevent, and it is only visible from up here.
+func TestTheSameWordInTwoFilesIsRefused(t *testing.T) {
+	_, err := extract(input("testdata/twice"), Options{Context: "shop", Files: []string{"*.GLOSSARY.md"}})
+	if err == nil {
+		t.Fatal("two definitions of one word produced a fragment")
+	}
+	if !strings.Contains(err.Error(), "Order is already defined in") {
+		t.Errorf("refusal is %q", err)
+	}
+}
+
+// The fragment is committed and compared by gen:check. A map iterated in Go's
+// order would rewrite the file every run and turn every build into a diff.
+func TestOutputIsByteIdentical(t *testing.T) {
+	first := response(t).Files[0].Contents
+	for i := 0; i < 5; i++ {
+		if again := response(t).Files[0].Contents; again != first {
+			t.Fatal("two runs over the same tree produced different fragments")
+		}
+	}
+}
+
+// The whole fragment, so a field that changes shape shows up as a diff rather
+// than slipping past every assertion above.
+func TestGoldenFragment(t *testing.T) {
+	got := response(t).Files[0].Contents
+
+	if *update {
+		if err := os.WriteFile(goldenPath, []byte(got), 0o644); err != nil {
+			t.Fatal(err)
+		}
+		t.Log("golden fragment rewritten")
+
+		return
+	}
+
+	want, err := os.ReadFile(goldenPath)
+	if err != nil {
+		t.Fatalf("reading the golden fragment: %v (run `go test ./plugins/extract-glossary -update`)", err)
+	}
+	if string(want) != got {
+		t.Errorf("the fragment differs from the golden file\n%s", firstDifference(string(want), got))
+	}
+}
+
+func warnedAbout(resp plugin.Response, substring string) bool {
+	for _, d := range resp.Warnings() {
+		if strings.Contains(d.Message, substring) {
+			return true
+		}
+	}
+
+	return false
+}
+
+func firstDifference(want, got string) string {
+	a := strings.Split(want, "\n")
+	b := strings.Split(got, "\n")
+	for i := 0; i < len(a) && i < len(b); i++ {
+		if a[i] != b[i] {
+			return "line " + strconv.Itoa(i+1) + ":\n  want: " + a[i] + "\n  got:  " + b[i]
+		}
+	}
+
+	return "want " + strconv.Itoa(len(a)) + " lines, got " + strconv.Itoa(len(b))
+}

package/plugins/extract-glossary/main.go

@@ -0,0 +1,59 @@
+// Command extract-glossary reads the vocabulary a bounded context speaks, as
+// the GLOSSARY.md it is already written in, and answers with a catalog
+// fragment.
+//
+// The glossary is the one file in a service that is written for a person and
+// read by everyone: it says what a word means inside the boundary, and what it
+// does NOT mean, which is where the confusion it was written to settle lives.
+// Nothing generates it and nothing should - a definition is a decision about
+// language, not a fact about code - so this plugin only reads.
+//
+// What it refuses is as much the point as what it parses. A table, a bullet
+// list, a heading per term: all of them hold the same words, and every one of
+// them makes the negative half of an entry either impossible to write or
+// impossible to find. One shape, held to here, is what lets a page put "is"
+// and "is not" on two lines everywhere in the estate. The format is described
+// in plugins/README.md and held to by parse_test.go.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// Options are what the manifest tells the extractor.
+type Options struct {
+	// Context is the bounded context whose vocabulary this is. It is asked for
+	// rather than derived because the file sits beside a SERVICE - shop.oms
+	// keeps one, and the words in it belong to shop. Left out, the name of the
+	// input directory, which is right only when the two coincide.
+	Context string `json:"context,omitempty"`
+
+	// Files are the glossaries to read, as globs relative to the input root.
+	// Left out, `GLOSSARY.md` at the root of it, which is where the layout
+	// rules put it - beside the README.
+	Files []string `json:"files,omitempty"`
+
+	// Out names the fragment file.
+	Out string `json:"out,omitempty"`
+}
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-extract-glossary:", err)
+		os.Exit(1)
+	}
+}
+
+func run(stdin io.Reader, stdout io.Writer) error {
+	return plugin.Serve(stdin, stdout, descriptor(), func(req plugin.Request, opts Options) (plugin.Response, error) {
+		if req.Input.Root == "" {
+			return plugin.Response{}, fmt.Errorf("no input root: an extractor has nothing to read")
+		}
+
+		return extract(req.Input, opts)
+	})
+}

package/plugins/extract-glossary/options.schema.json

@@ -0,0 +1,21 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context whose vocabulary this is. A glossary sits beside a service, and the words in it belong to the context that service is in, so shop/oms/GLOSSARY.md is read as shop. Left out, the name of the input directory.",
+      "examples": ["auth", "shop"]
+    },
+    "files": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "The glossaries to read, as globs relative to the input root. Left out, GLOSSARY.md at the root of it.",
+      "examples": [["GLOSSARY.md"], ["docs/GLOSSARY.md"]]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory. Left out, glossary.json."
+    }
+  }
+}