@shortlink-org/portolan 0.1.0

package/plugins/extract-glossary/parse.go

@@ -0,0 +1,214 @@
+package main
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// The format, in one place.
+//
+//	# Glossary — auth
+//
+//	One meaning per word inside this context.
+//
+//	**Session.** Proof that a user logged in, how long that proof is good for,
+//	and whether it has been taken away.
+//
+// A title, an optional line or two saying what the vocabulary covers, then one
+// paragraph per term in alphabetical order. The paragraph opens with the term
+// in bold and the full stop inside the bold, so `**Email address.**` names a
+// two-word term and nothing has to guess where the name ends. Everything after
+// it is the definition, carried through as written.
+//
+// That is the whole format. Nothing here reads the prose for structure: a
+// glossary is a person explaining a word to another person, and a parser that
+// went looking for shapes inside the explanation would be a parser telling an
+// estate how to phrase itself.
+var (
+	titleLine = regexp.MustCompile(`^#\s+Glossary\b`)
+	entryOpen = regexp.MustCompile(`^\*\*(.+?)\.\*\*\s*(.*)$`)
+	listItem  = regexp.MustCompile(`^([-*+]|\d+\.)\s`)
+)
+
+// A paragraph of the file, flattened to one line, and where it started.
+//
+// Flattening is what makes the rest of this file about words rather than about
+// line breaks: a glossary is hard-wrapped at whatever width its author likes,
+// and a soft break inside a paragraph is a space in every markdown renderer
+// there is. The line number survives because it is the only thing an error
+// message can point at.
+type paragraph struct {
+	line int
+	text string
+}
+
+// blocks splits a file into paragraphs on blank lines.
+func blocks(src string) []paragraph {
+	var out []paragraph
+
+	lines := strings.Split(strings.ReplaceAll(src, "\r\n", "\n"), "\n")
+	start := 0
+	var held []string
+	flush := func() {
+		if len(held) == 0 {
+			return
+		}
+		out = append(out, paragraph{line: start, text: strings.Join(held, " ")})
+		held = nil
+	}
+	for i, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if trimmed == "" {
+			flush()
+
+			continue
+		}
+		if len(held) == 0 {
+			start = i + 1
+		}
+		held = append(held, trimmed)
+	}
+	flush()
+
+	return out
+}
+
+// slug turns a term into the kebab-case form ids and urls use: "Email address"
+// becomes email-address, "Password policy" becomes password-policy.
+func slug(name string) string {
+	var b strings.Builder
+
+	dash := false
+	for _, r := range strings.ToLower(name) {
+		switch {
+		case r >= 'a' && r <= 'z', r >= '0' && r <= '9':
+			b.WriteRune(r)
+			dash = false
+		default:
+			if !dash && b.Len() > 0 {
+				b.WriteRune('-')
+				dash = true
+			}
+		}
+	}
+
+	return strings.Trim(b.String(), "-")
+}
+
+func where(file string, line int) string {
+	return fmt.Sprintf("%s:%d: ", file, line)
+}
+
+// short quotes the head of a paragraph, for an error that has to say what it
+// found instead of what it wanted.
+func short(text string) string {
+	runes := []rune(text)
+	if len(runes) > 40 {
+		return `"` + string(runes[:40]) + `…"`
+	}
+
+	return `"` + text + `"`
+}
+
+// refuse names what a paragraph is, when it is not an entry. A paragraph
+// before the first entry is the preamble and is allowed to be anything; after
+// one, everything is an entry, and the shapes worth naming are the shapes a
+// glossary is otherwise written in.
+func refuse(text string, started bool) string {
+	switch {
+	case strings.HasPrefix(text, "|"):
+		return "a table: a glossary is prose, one paragraph per term, so that an entry has room to say what the term is not"
+	case strings.HasPrefix(text, "#"):
+		return "a heading under the title: a term is a paragraph, not a section of its own"
+	case listItem.MatchString(text):
+		return "a list: a term is a paragraph opening with **Term.**"
+	case started:
+		return "a paragraph naming no term; after the first entry every paragraph is one, and it opens with **Term.**"
+	}
+
+	return ""
+}
+
+// parseGlossary reads one file into terms, the notes worth making about it,
+// and the reasons it cannot be read at all.
+//
+// Errors and warnings are kept apart all the way up: an error is something the
+// catalog cannot hold, a warning is something a person should go and write.
+func parseGlossary(file, context, src string) (terms []catalog.Term, warns, errs []string) {
+	paras := blocks(src)
+	if len(paras) == 0 {
+		return nil, nil, []string{file + ": the file is empty"}
+	}
+	if !titleLine.MatchString(paras[0].text) {
+		return nil, nil, []string{where(file, paras[0].line) +
+			"a glossary opens with `# Glossary — <context>`, and this file opens with " + short(paras[0].text)}
+	}
+
+	seen := map[string]int{}
+	previous := ""
+	started := false
+	for _, p := range paras[1:] {
+		if !strings.HasPrefix(p.text, "**") {
+			if msg := refuse(p.text, started); msg != "" {
+				errs = append(errs, where(file, p.line)+msg)
+			}
+
+			continue
+		}
+		started = true
+
+		m := entryOpen.FindStringSubmatch(p.text)
+		if m == nil {
+			errs = append(errs, where(file, p.line)+
+				"an entry opens with the term in bold and the full stop inside it, `**Session.**`")
+
+			continue
+		}
+		name := strings.TrimSpace(m[1])
+		body := strings.TrimSpace(m[2])
+		id := slug(name)
+		if id == "" {
+			errs = append(errs, where(file, p.line)+"a term with no name")
+
+			continue
+		}
+		if body == "" {
+			errs = append(errs, where(file, p.line)+name+" says nothing")
+
+			continue
+		}
+
+		if at, taken := seen[id]; taken {
+			errs = append(errs, where(file, p.line)+name+fmt.Sprintf(" is already defined on line %d", at))
+
+			continue
+		}
+		seen[id] = p.line
+
+		// Order is a warning because it costs a reader a moment and costs the
+		// catalog nothing: every page sorts what it draws anyway.
+		lower := strings.ToLower(name)
+		if previous != "" && lower < previous {
+			warns = append(warns, where(file, p.line)+name+" sits after "+previous+"; the glossary is alphabetical")
+		}
+		previous = lower
+
+		terms = append(terms, catalog.Term{
+			ID:         context + "." + id,
+			Slug:       id,
+			Context:    context,
+			Name:       name,
+			Definition: body,
+			Source:     fmt.Sprintf("%s:%d", file, p.line),
+		})
+	}
+
+	if !started && len(errs) == 0 {
+		warns = append(warns, file+": a glossary with no terms in it")
+	}
+
+	return terms, warns, errs
+}

package/plugins/extract-glossary/parse_test.go

@@ -0,0 +1,203 @@
+package main
+
+import (
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+const sample = `# Glossary — auth
+
+One meaning per word inside this context. The code, the events and the API
+spell these the same way.
+
+**Email address.** The address a user logs in with, normalised on creation.
+
+**Session.** Proof that a user logged in, and how long that proof is good for,
+and whether it has been taken away.
+
+**Version.** The number the store compares before writing an aggregate. Zero
+means never stored.
+`
+
+const file = "examples/auth/GLOSSARY.md"
+
+func parsed(t *testing.T, src string) []catalog.Term {
+	t.Helper()
+
+	terms, _, errs := parseGlossary(file, "auth", src)
+	if len(errs) > 0 {
+		t.Fatalf("errors: %s", strings.Join(errs, "\n"))
+	}
+
+	return terms
+}
+
+func refused(t *testing.T, src string) string {
+	t.Helper()
+
+	_, _, errs := parseGlossary(file, "auth", src)
+	if len(errs) == 0 {
+		t.Fatal("parsed without complaint")
+	}
+
+	return strings.Join(errs, "\n")
+}
+
+func warned(t *testing.T, src string) string {
+	t.Helper()
+
+	_, warns, errs := parseGlossary(file, "auth", src)
+	if len(errs) > 0 {
+		t.Fatalf("errors: %s", strings.Join(errs, "\n"))
+	}
+
+	return strings.Join(warns, "\n")
+}
+
+func term(t *testing.T, terms []catalog.Term, name string) catalog.Term {
+	t.Helper()
+
+	for _, candidate := range terms {
+		if candidate.Name == name {
+			return candidate
+		}
+	}
+	t.Fatalf("no term called %q", name)
+
+	return catalog.Term{}
+}
+
+func TestTheDefinitionIsTheParagraph(t *testing.T) {
+	session := term(t, parsed(t, sample), "Session")
+
+	want := "Proof that a user logged in, and how long that proof is good for, and whether it has been taken away."
+	if session.Definition != want {
+		t.Errorf("definition is %q, want %q", session.Definition, want)
+	}
+}
+
+// The hard wrap in the file is a soft break in markdown, and a definition that
+// carried it would be a definition nothing could put on a card.
+func TestParagraphIsOneLine(t *testing.T) {
+	for _, term := range parsed(t, sample) {
+		if strings.ContainsAny(term.Definition, "\n") {
+			t.Errorf("%s carries a line break", term.Name)
+		}
+	}
+}
+
+func TestTwoWordTerm(t *testing.T) {
+	address := term(t, parsed(t, sample), "Email address")
+
+	if address.Slug != "email-address" {
+		t.Errorf("slug is %q", address.Slug)
+	}
+	if address.ID != "auth.email-address" {
+		t.Errorf("id is %q", address.ID)
+	}
+	if address.Context != "auth" {
+		t.Errorf("context is %q", address.Context)
+	}
+}
+
+func TestSourceIsTheLineTheEntryStartsOn(t *testing.T) {
+	if got := term(t, parsed(t, sample), "Session").Source; got != file+":8" {
+		t.Errorf("source is %q, want %s:8", got, file)
+	}
+}
+
+func TestPreambleIsNotATerm(t *testing.T) {
+	if terms := parsed(t, sample); len(terms) != 3 {
+		names := []string{}
+		for _, term := range terms {
+			names = append(names, term.Name)
+		}
+		t.Errorf("read %d terms: %s", len(terms), strings.Join(names, ", "))
+	}
+}
+
+func TestTableIsRefused(t *testing.T) {
+	src := "# Glossary — auth\n\n| Term | Meaning |\n| --- | --- |\n| Session | Proof. |\n"
+
+	if got := refused(t, src); !strings.Contains(got, "prose") {
+		t.Errorf("refusal is %q", got)
+	}
+}
+
+func TestHeadingPerTermIsRefused(t *testing.T) {
+	src := "# Glossary — auth\n\n## Session\n\nProof that a user logged in.\n"
+
+	if got := refused(t, src); !strings.Contains(got, "a term is a paragraph") {
+		t.Errorf("refusal is %q", got)
+	}
+}
+
+func TestListIsRefused(t *testing.T) {
+	src := "# Glossary — auth\n\n- **Session.** Proof that a user logged in.\n"
+
+	if got := refused(t, src); !strings.Contains(got, "a list") {
+		t.Errorf("refusal is %q", got)
+	}
+}
+
+func TestAFileThatIsNotAGlossaryIsRefused(t *testing.T) {
+	src := "# Sessions\n\n**Session.** Proof that a user logged in.\n"
+
+	if got := refused(t, src); !strings.Contains(got, "opens with `# Glossary") {
+		t.Errorf("refusal is %q", got)
+	}
+}
+
+// A word with two meanings inside one context is the failure the glossary is
+// written to prevent, so it is the one duplication that cannot be a warning.
+func TestTheSameWordTwiceIsRefused(t *testing.T) {
+	src := sample + "\n**Session.** Something else entirely.\n"
+
+	if got := refused(t, src); !strings.Contains(got, "already defined on line 8") {
+		t.Errorf("refusal is %q", got)
+	}
+}
+
+func TestOutOfOrderIsAWarning(t *testing.T) {
+	src := "# Glossary — auth\n\n**Lockout.** An account refusing passwords.\n\n**Locked.** The state of a lockout while it refuses.\n"
+
+	if got := warned(t, src); !strings.Contains(got, "alphabetical") {
+		t.Errorf("warnings are %q", got)
+	}
+}
+
+func TestAnEntryThatNamesNothing(t *testing.T) {
+	src := "# Glossary — auth\n\n**Session** proof that a user logged in.\n"
+
+	if got := refused(t, src); !strings.Contains(got, "the full stop inside it") {
+		t.Errorf("refusal is %q", got)
+	}
+}
+
+// The estate's own glossaries parse, and are held to the format they document.
+func TestTheEstatesOwnGlossaries(t *testing.T) {
+	for _, tt := range []struct{ path, context string }{
+		{"../../examples/auth/GLOSSARY.md", "auth"},
+		{"../../examples/shop/oms/GLOSSARY.md", "shop"},
+	} {
+		t.Run(tt.path, func(t *testing.T) {
+			src, err := os.ReadFile(tt.path)
+			if err != nil {
+				t.Fatal(err)
+			}
+			terms, warns, errs := parseGlossary(tt.path, tt.context, string(src))
+			if len(errs) > 0 {
+				t.Fatalf("errors: %s", strings.Join(errs, "\n"))
+			}
+			if len(warns) > 0 {
+				t.Errorf("warnings: %s", strings.Join(warns, "\n"))
+			}
+			if len(terms) == 0 {
+				t.Error("no terms read")
+			}
+		})
+	}
+}

package/plugins/extract-go/aggregate.go

@@ -0,0 +1,214 @@
+package main
+
+import (
+	"os"
+	"path"
+	"path/filepath"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// extractAggregate reads one discovered aggregate domain package.
+//
+// The layout is the claim: a directory there is an aggregate, the struct named
+// after it is the root, `vo/` holds its value objects and `event/` the facts it
+// publishes. Nothing is inferred from a comment or a marker interface, so a
+// package that does not follow the layout produces a diagnostic instead of a
+// half-right aggregate.
+func extractAggregate(root, aggregateName, domainPath string, layout sourceLayout, svcID string, b *plugin.Builder) (catalog.Aggregate, bool) {
+	pkg, err := parsePkg(root, domainPath)
+	if err != nil {
+		if !os.IsNotExist(err) {
+			b.Warn(aggregateID(svcID, aggregateName), domainPath+" could not be parsed: "+err.Error())
+		}
+
+		return catalog.Aggregate{}, false
+	}
+
+	id := aggregateID(svcID, slug(aggregateName))
+	name := title(pkg.name)
+
+	aggregate := catalog.Aggregate{
+		ID:           id,
+		Slug:         slug(aggregateName),
+		Name:         name,
+		Readme:       aggregateReadme(root, domainPath, pkg.name, name, pkg.doc()),
+		Entities:     []catalog.Block{},
+		ValueObjects: []catalog.Block{},
+		Operations:   []catalog.Operation{},
+		Events:       []catalog.Event{},
+	}
+
+	for _, decl := range pkg.structs() {
+		if !exported(decl.name) {
+			continue
+		}
+
+		aggregate.Entities = append(aggregate.Entities, catalog.Block{
+			ID:     blockID(id, slug(decl.name)),
+			Slug:   slug(decl.name),
+			Name:   decl.name,
+			Doc:    decl.doc,
+			Fields: fields(decl.fields),
+		})
+	}
+
+	// The root is the entity named after its package: package user holds User,
+	// and package price_list holds PriceList. It is a rule rather than a guess,
+	// and a package that breaks it is not read as an aggregate at all. Taking
+	// whichever struct came first instead would put a package of error types
+	// on the page as a model with a root and seven fields, and a reader
+	// believes a table; a warning and no page is the honest answer.
+	aggregate.Root = pascal(pkg.name)
+	if !hasBlock(aggregate.Entities, aggregate.Root) {
+		if len(aggregate.Entities) == 0 {
+			b.Warn(id, domainPath+" declares no exported struct, so the aggregate has no root")
+
+			return catalog.Aggregate{}, false
+		}
+
+		b.Warn(id, domainPath+" has no struct called "+pascal(pkg.name)+", so it is not read as an aggregate; the root is the struct named after its package")
+
+		return catalog.Aggregate{}, false
+	}
+
+	aggregate.ValueObjects = extractValueObjects(root, domainPath, id, b)
+	aggregate.Enums = extractEnums(root, domainPath, id, pkg, b)
+	aggregate.Events = extractEvents(root, aggregateName, domainPath, layout, id, b)
+	aggregate.Lifecycle = readLifecycle(pkg, aggregate.Root, aggregate.Events, id, b)
+
+	return aggregate, true
+}
+
+// extractValueObjects reads vo/* below a discovered aggregate domain package.
+//
+// Each directory there is one value object, and the exported struct inside it
+// is its shape. `rules/` is skipped: a validation specification is how the
+// value object refuses a value, not part of what it holds.
+func extractValueObjects(root, domainPath, aggID string, b *plugin.Builder) []catalog.Block {
+	out := []catalog.Block{}
+
+	for _, name := range subdirs(root, path.Join(domainPath, "vo")) {
+		if name == "rules" {
+			continue
+		}
+
+		pkg, err := parsePkg(root, path.Join(domainPath, "vo", name))
+		if err != nil {
+			continue
+		}
+
+		found := false
+		for _, decl := range pkg.structs() {
+			if !exported(decl.name) {
+				continue
+			}
+
+			doc := decl.doc
+			if doc == "" {
+				doc = firstSentenceOrAll(pkg.doc())
+			}
+
+			// Qualified the way Go refers to it, so that the value object and
+			// the field that holds it are visibly the same thing: User.Password
+			// is a `password.Hash`, and a block called just `Hash` says nothing
+			// about which one.
+			label := qualified(pkg.name, decl.name)
+
+			out = append(out, catalog.Block{
+				ID:     blockID(aggID, slug(label)),
+				Slug:   slug(label),
+				Name:   label,
+				Doc:    doc,
+				Fields: fields(decl.fields),
+			})
+			found = true
+		}
+
+		if !found {
+			b.Warn(aggID, path.Join(domainPath, "vo", name)+" declares no exported struct; skipped")
+		}
+	}
+
+	return out
+}
+
+func hasBlock(blocks []catalog.Block, name string) bool {
+	for i := range blocks {
+		if blocks[i].Name == name {
+			return true
+		}
+	}
+
+	return false
+}
+
+// qualified is pkg.Name, unless the package is named after the type it holds -
+// token.Token adds nothing over Token.
+func qualified(pkg, name string) string {
+	if strings.EqualFold(pkg, name) {
+		return name
+	}
+
+	return pkg + "." + name
+}
+
+func exported(name string) bool {
+	return name != "" && name[0] >= 'A' && name[0] <= 'Z'
+}
+
+// aggregateReadme prefers the package's README.md, which is written for a
+// reader and can draw the states, over the package comment, which is written
+// for whoever opens the file next. Same preference as operationDoc, for the
+// same reason. The comment is a fallback, not a second source: a package that
+// has both is described by its README alone.
+func aggregateReadme(root, domainPath, pkgName, name, doc string) string {
+	if md := readFile(filepath.Join(root, filepath.FromSlash(domainPath), "README.md")); md != "" {
+		return md
+	}
+
+	return readme(pkgName, name, doc)
+}
+
+// readme turns a package comment into the markdown the catalog carries. The
+// heading is added because every other readme in a catalog has one, and a page
+// that starts mid-paragraph reads as a fragment of something else.
+func readme(pkgName, name, doc string) string {
+	doc = withoutPackagePrefix(pkgName, strings.TrimSpace(doc))
+	if doc == "" {
+		return ""
+	}
+
+	return "# " + name + "\n\n" + doc
+}
+
+// withoutPackagePrefix drops the "Package user " that Go doc convention puts at
+// the front of a package comment.
+//
+// It is a convention for godoc, where the sentence is read next to the package
+// clause. On a page headed "User" it reads as a leftover from somewhere else,
+// and the sentence works perfectly well without it.
+func withoutPackagePrefix(pkgName, doc string) string {
+	return withoutLeading("Package "+pkgName+" ", doc)
+}
+
+// withoutLeading is the same for anything else Go doc convention names before
+// it says anything: a type comment opens with the type.
+func withoutLeading(prefix, doc string) string {
+	rest, ok := strings.CutPrefix(doc, prefix)
+	if !ok {
+		return doc
+	}
+
+	runes := []rune(rest)
+	if len(runes) == 0 {
+		return doc
+	}
+	if runes[0] >= 'a' && runes[0] <= 'z' {
+		runes[0] = runes[0] - 'a' + 'A'
+	}
+
+	return string(runes)
+}