@shortlink-org/portolan 0.1.0 → 0.2.1

package/plugins/extract-glossary/parse.go

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

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

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