@shortlink-org/portolan 0.1.0 → 0.2.0

package/plugins/extract-adr/parse_test.go

@@ -1,405 +0,0 @@
-package main
-
-import (
-	"strings"
-	"testing"
-
-	"github.com/shortlink-org/portolan/catalog"
-)
-
-const sample = `# auth.0003 — Session expiry publishes no event
-
-- **Status:** accepted
-- **Date:** 2026-08-22
-- **Scope:** auth.auth
-- **Supersedes:** auth.0001, auth.0002
-- **Relates:** auth.auth.session.SessionEnded, shop.cart, checkout
-- **Note:** how a revocation is kept out of the cache was decided again in
-  auth.0010; the drop turned out not to be enough.
-
-## Context and Problem Statement
-
-A session stops being usable at ` + "`ExpiresAt`" + `.
-
-### An aside
-
-Kept as written.
-
-## Decision Outcome
-
-No event.
-`
-
-func parsed(t *testing.T, src string) catalog.Adr {
-	t.Helper()
-
-	adr, errs := parseAdr("examples/auth/docs/adr/0003-expiry-publishes-nothing.md", src, defaults{})
-	if len(errs) > 0 {
-		t.Fatalf("errors: %s", strings.Join(errs, "\n"))
-	}
-
-	return adr
-}
-
-func refused(t *testing.T, src string) string {
-	t.Helper()
-
-	_, errs := parseAdr("examples/auth/docs/adr/0003-expiry-publishes-nothing.md", src, defaults{})
-	if len(errs) == 0 {
-		t.Fatal("parsed without complaint")
-	}
-
-	return strings.Join(errs, "\n")
-}
-
-// Replaces one meta bullet with another, so a test says what it is about and
-// nothing else.
-func with(bullet, replacement string) string {
-	return strings.Replace(sample, bullet, replacement, 1)
-}
-
-func TestTheTitleCarriesTheIDAndTheTitle(t *testing.T) {
-	adr := parsed(t, sample)
-	if adr.ID != "auth.0003" || adr.Number != 3 || adr.Title != "Session expiry publishes no event" {
-		t.Errorf("id %q, number %d, title %q", adr.ID, adr.Number, adr.Title)
-	}
-}
-
-// The slug is the id with its dots opened out, then the file's own kebab: the
-// id says which record this is and the file's name says what it was about,
-// which is the slug the catalog carried when these were written by hand.
-func TestTheSlugIsTheIDAndTheFileName(t *testing.T) {
-	adr := parsed(t, sample)
-	if adr.Slug != "auth-0003-expiry-publishes-nothing" {
-		t.Errorf("slug = %q", adr.Slug)
-	}
-	if adr.Source != "examples/auth/docs/adr/0003-expiry-publishes-nothing.md" {
-		t.Errorf("source = %q", adr.Source)
-	}
-}
-
-func TestAFileNumberedAwayFromItsRecordIsRefused(t *testing.T) {
-	_, errs := parseAdr("docs/adr/0009-expiry-publishes-nothing.md", sample, defaults{})
-	if len(errs) != 1 || !strings.Contains(errs[0], "numbered 0009") {
-		t.Errorf("errors: %v", errs)
-	}
-}
-
-func TestTheMetaBulletsAreRead(t *testing.T) {
-	adr := parsed(t, sample)
-	if adr.Status != catalog.AdrAccepted || adr.Date != "2026-08-22" {
-		t.Errorf("status %q, date %q", adr.Status, adr.Date)
-	}
-	if adr.Scope != (catalog.AdrScope{Kind: "service", Service: "auth.auth"}) {
-		t.Errorf("scope = %+v", adr.Scope)
-	}
-	if strings.Join(adr.Supersedes, ",") != "auth.0001,auth.0002" {
-		t.Errorf("supersedes = %v", adr.Supersedes)
-	}
-}
-
-// A bullet wrapped onto the next line is one bullet: the break is the author's
-// line width and carries no meaning, so it closes up into a space.
-func TestAWrappedBulletIsOneValue(t *testing.T) {
-	adr := parsed(t, sample)
-	want := "how a revocation is kept out of the cache was decided again in auth.0010; the drop turned out not to be enough."
-	if adr.Note != want {
-		t.Errorf("note = %q", adr.Note)
-	}
-}
-
-// The scope's shape says which of the three kinds it is, and nothing else can:
-// an extractor sees one service's tree and has no catalog to look a name up in.
-func TestScopeKindComesFromTheNumberOfSegments(t *testing.T) {
-	for _, c := range []struct {
-		written string
-		want    catalog.AdrScope
-	}{
-		{"org", catalog.AdrScope{Kind: "org"}},
-		{"", catalog.AdrScope{Kind: "org"}},
-		{"payments", catalog.AdrScope{Kind: "context", Context: "payments"}},
-		{"shop.cart", catalog.AdrScope{Kind: "service", Service: "shop.cart"}},
-	} {
-		adr := parsed(t, with("- **Scope:** auth.auth", "- **Scope:** "+c.written))
-		if adr.Scope != c.want {
-			t.Errorf("%q read as %+v, want %+v", c.written, adr.Scope, c.want)
-		}
-	}
-}
-
-// One list in the file, three in the catalog. An author should not have to
-// remember which of the three a name belongs in, so the name's shape says.
-func TestRelatesIsSortedByShape(t *testing.T) {
-	adr := parsed(t, sample)
-	if strings.Join(adr.Relates.Events, ",") != "auth.auth.session.SessionEnded" {
-		t.Errorf("events = %v", adr.Relates.Events)
-	}
-	if strings.Join(adr.Relates.Services, ",") != "shop.cart" {
-		t.Errorf("services = %v", adr.Relates.Services)
-	}
-	if strings.Join(adr.Relates.Flows, ",") != "checkout" {
-		t.Errorf("flows = %v", adr.Relates.Flows)
-	}
-}
-
-func TestARelationOfNoRecognisableShapeIsRefused(t *testing.T) {
-	errs := refused(t, with("- **Relates:** auth.auth.session.SessionEnded, shop.cart, checkout", "- **Relates:** auth.auth.session"))
-	if !strings.Contains(errs, "not the shape of an event, a service or a flow") {
-		t.Errorf("errors: %s", errs)
-	}
-}
-
-// The body is frozen history. It starts at the first `##` and is carried into
-// the catalog exactly as written, headings and all, because nothing on an ADR
-// page is ever regenerated from the model as it stands now.
-func TestTheBodyStartsAtTheFirstSectionAndIsUnedited(t *testing.T) {
-	adr := parsed(t, sample)
-	if !strings.HasPrefix(adr.Body, "## Context and Problem Statement\n") {
-		t.Errorf("body starts %q", adr.Body[:40])
-	}
-	if !strings.Contains(adr.Body, "### An aside") || !strings.Contains(adr.Body, "`ExpiresAt`") {
-		t.Errorf("body = %q", adr.Body)
-	}
-	if !strings.HasSuffix(adr.Body, "No event.\n") {
-		t.Errorf("body ends %q", adr.Body[len(adr.Body)-20:])
-	}
-}
-
-func TestWhatARecordCannotBeReadWithout(t *testing.T) {
-	for key, bullet := range map[string]string{
-		"Status": "- **Status:** accepted",
-		"Date":   "- **Date:** 2026-08-22",
-		"Scope":  "- **Scope:** auth.auth",
-	} {
-		errs := refused(t, strings.Replace(sample, bullet+"\n", "", 1))
-		if !strings.Contains(errs, "says no \""+key+"\"") {
-			t.Errorf("dropping %s gave: %s", key, errs)
-		}
-	}
-}
-
-func TestAStatusOrDateThatIsNeitherIsRefused(t *testing.T) {
-	if errs := refused(t, with("- **Status:** accepted", "- **Status:** agreed")); !strings.Contains(errs, "is not a status") {
-		t.Errorf("errors: %s", errs)
-	}
-	if errs := refused(t, with("- **Date:** 2026-08-22", "- **Date:** last August")); !strings.Contains(errs, "is not a date") {
-		t.Errorf("errors: %s", errs)
-	}
-}
-
-// Supersession is a two-way fact, and half of it recorded is a bug. Both
-// halves that live in one file are held against each other here; the halves in
-// two files are held against each other by extract.
-func TestHalfARecordedSupersessionIsRefused(t *testing.T) {
-	errs := refused(t, with("- **Status:** accepted", "- **Status:** superseded"))
-	if !strings.Contains(errs, "superseded and says by what") {
-		t.Errorf("errors: %s", errs)
-	}
-
-	errs = refused(t, with("- **Supersedes:** auth.0001, auth.0002", "- **Superseded by:** auth.0007"))
-	if !strings.Contains(errs, `its status is "accepted"`) {
-		t.Errorf("errors: %s", errs)
-	}
-}
-
-func TestABulletTheFormatDoesNotHaveIsRefused(t *testing.T) {
-	errs := refused(t, with("- **Note:**", "- **Owner:**"))
-	if !strings.Contains(errs, "is not one of the bullets a record carries") {
-		t.Errorf("errors: %s", errs)
-	}
-}
-
-// The head is bullets and nothing else. A paragraph that drifted above the
-// first `##` would be read by a person and dropped by the extractor, and the
-// record on the page would quietly be missing its opening.
-func TestProseBetweenTheTitleAndTheRecordIsRefused(t *testing.T) {
-	errs := refused(t, with("## Context and Problem Statement", "A stray paragraph.\n\n## Context and Problem Statement"))
-	if !strings.Contains(errs, "only meta bullets belong") {
-		t.Errorf("errors: %s", errs)
-	}
-}
-
-func TestARecordWithNoBodyIsRefused(t *testing.T) {
-	errs := refused(t, "# auth.0003 — A title\n\n- **Status:** accepted\n- **Date:** 2026-08-22\n- **Scope:** auth.auth\n")
-	if !strings.Contains(errs, "no body") {
-		t.Errorf("errors: %s", errs)
-	}
-}
-
-func TestATitleThatIsNotOneIsRefused(t *testing.T) {
-	if errs := refused(t, strings.Replace(sample, "auth.0003 — Session", "auth.0003 - Session", 1)); !strings.Contains(errs, "em dash") {
-		t.Errorf("errors: %s", errs)
-	}
-	if errs := refused(t, strings.Replace(sample, "auth.0003 —", "auth.3 —", 1)); !strings.Contains(errs, "four padded digits") {
-		t.Errorf("errors: %s", errs)
-	}
-}
-
-// Every mistake in a header, not the first one: a file with two typos in it
-// should be fixed once.
-func TestEveryMistakeIsReported(t *testing.T) {
-	src := with("- **Status:** accepted", "- **Status:** agreed")
-	src = strings.Replace(src, "- **Date:** 2026-08-22", "- **Date:** last August", 1)
-	if _, errs := parseAdr("docs/adr/0003-expiry-publishes-nothing.md", src, defaults{}); len(errs) != 2 {
-		t.Errorf("errors: %v", errs)
-	}
-}
-
-// The other format: what adr-tools writes. The number and the title are on the
-// title line, the date is a line of its own, and the status is the record's
-// first section. The id's prefix and the scope come from the step, because
-// the format has no place for either.
-const toolsSample = `# 3. Use DTO
-
-Date: 2024-09-10
-
-## Status
-
-Accepted
-
-## Context
-
-Every supplier answers in its own shape.
-
-## Decision
-
-Translate at the boundary.
-`
-
-func parsedTools(t *testing.T, src string, scope string) catalog.Adr {
-	t.Helper()
-
-	adr, errs := parseAdr("etg/aviasupp/docs/ADR/0003-use-dto.md", src, defaults{Scope: scope})
-	if len(errs) > 0 {
-		t.Fatalf("errors: %s", strings.Join(errs, "\n"))
-	}
-
-	return adr
-}
-
-func refusedTools(t *testing.T, src string) string {
-	t.Helper()
-
-	_, errs := parseAdr("etg/aviasupp/docs/ADR/0003-use-dto.md", src, defaults{Scope: "avia.aviasupp"})
-	if len(errs) == 0 {
-		t.Fatal("parsed without complaint")
-	}
-
-	return strings.Join(errs, "\n")
-}
-
-func TestAnAdrToolsRecordIsRead(t *testing.T) {
-	adr := parsedTools(t, toolsSample, "avia.aviasupp")
-	if adr.ID != "aviasupp.0003" || adr.Number != 3 || adr.Title != "Use DTO" {
-		t.Errorf("id %q, number %d, title %q", adr.ID, adr.Number, adr.Title)
-	}
-	if adr.Slug != "aviasupp-0003-use-dto" {
-		t.Errorf("slug = %q", adr.Slug)
-	}
-	if adr.Status != catalog.AdrAccepted || adr.Date != "2024-09-10" {
-		t.Errorf("status %q, date %q", adr.Status, adr.Date)
-	}
-	if adr.Scope.Kind != "service" || adr.Scope.Service != "avia.aviasupp" {
-		t.Errorf("scope = %+v", adr.Scope)
-	}
-	// The status section is part of the record, and the record is kept whole.
-	if !strings.HasPrefix(adr.Body, "## Status\n\nAccepted\n\n## Context") {
-		t.Errorf("body = %q", adr.Body)
-	}
-}
-
-// The prefix follows the scope the way the estate's own records do: the
-// service, the context, or "org".
-func TestTheIDPrefixComesFromTheScope(t *testing.T) {
-	for scope, id := range map[string]string{
-		"avia.aviasupp": "aviasupp.0003",
-		"payments":      "payments.0003",
-		"org":           "org.0003",
-		"":              "org.0003",
-	} {
-		if adr := parsedTools(t, toolsSample, scope); adr.ID != id {
-			t.Errorf("scope %q: id = %q", scope, adr.ID)
-		}
-	}
-	if adr := parsedTools(t, toolsSample, ""); adr.Scope.Kind != "org" {
-		t.Errorf("no scope: %+v", adr.Scope)
-	}
-}
-
-// Supersession is written the way adr-tools writes it: in the Status section,
-// as a link to the other record, and the later statement wins.
-func TestAnAdrToolsSupersessionIsRead(t *testing.T) {
-	src := strings.Replace(toolsSample, "Accepted\n", "Accepted\n\nSuperseded by [5. Use schemas](0005-use-schemas.md)\n", 1)
-	adr := parsedTools(t, src, "avia.aviasupp")
-	if adr.Status != catalog.AdrSuperseded || adr.SupersededBy != "aviasupp.0005" {
-		t.Errorf("status %q, superseded by %q", adr.Status, adr.SupersededBy)
-	}
-
-	src = strings.Replace(toolsSample, "Accepted\n", "Accepted\n\nSupersedes [1. Record decisions](0001-record.md), ADR-0002\n", 1)
-	adr = parsedTools(t, src, "avia.aviasupp")
-	if strings.Join(adr.Supersedes, " ") != "aviasupp.0001" {
-		t.Errorf("supersedes = %v", adr.Supersedes)
-	}
-
-	src = strings.Replace(toolsSample, "Accepted\n", "Accepted\n\nSupersedes ADR-0001 and 2\n", 1)
-	if adr = parsedTools(t, src, "avia.aviasupp"); strings.Join(adr.Supersedes, " ") != "aviasupp.0001 aviasupp.0002" {
-		t.Errorf("bare numbers: supersedes = %v", adr.Supersedes)
-	}
-}
-
-func TestAStatusWordIsReadWhateverItsCase(t *testing.T) {
-	for _, word := range []string{"accepted", "ACCEPTED", "Accepted."} {
-		if adr := parsedTools(t, strings.Replace(toolsSample, "Accepted\n", word+"\n", 1), ""); adr.Status != catalog.AdrAccepted {
-			t.Errorf("%q read as %q", word, adr.Status)
-		}
-	}
-}
-
-func TestWhatAnAdrToolsRecordCannotBeReadWithout(t *testing.T) {
-	if errs := refusedTools(t, strings.Replace(toolsSample, "Date: 2024-09-10\n", "", 1)); !strings.Contains(errs, `no "Date:"`) {
-		t.Errorf("errors: %s", errs)
-	}
-	if errs := refusedTools(t, strings.Replace(toolsSample, "## Status\n\nAccepted\n", "", 1)); !strings.Contains(errs, "no `## Status` section") {
-		t.Errorf("errors: %s", errs)
-	}
-	if errs := refusedTools(t, strings.Replace(toolsSample, "Accepted", "Agreed", 1)); !strings.Contains(errs, `"Agreed" is not a status`) {
-		t.Errorf("errors: %s", errs)
-	}
-	if errs := refusedTools(t, strings.Replace(toolsSample, "Accepted", "Superseded by a later one", 1)); !strings.Contains(errs, "says by which one record") {
-		t.Errorf("errors: %s", errs)
-	}
-	if errs := refusedTools(t, strings.Replace(toolsSample, "Date: 2024-09-10", "Date: 2024-09-10\n\nWritten in a hurry.", 1)); !strings.Contains(errs, `only "Date:" belongs`) {
-		t.Errorf("errors: %s", errs)
-	}
-}
-
-// A MADR record that says no Scope is about whatever the step says its tree
-// is about, and only a record with neither is refused.
-func TestAMissingScopeFallsBackToTheStep(t *testing.T) {
-	src := with("- **Scope:** auth.auth\n", "")
-	adr, errs := parseAdr("examples/auth/docs/adr/0003-expiry-publishes-nothing.md", src, defaults{Scope: "auth"})
-	if len(errs) > 0 {
-		t.Fatalf("errors: %s", strings.Join(errs, "\n"))
-	}
-	if adr.Scope.Kind != "context" || adr.Scope.Context != "auth" {
-		t.Errorf("scope = %+v", adr.Scope)
-	}
-	if errs := refused(t, src); !strings.Contains(errs, `no "Scope"`) {
-		t.Errorf("errors: %s", errs)
-	}
-}
-
-// A record with no number in its title at all - written by hand into an
-// adr-tools tree - is numbered by its file. A MADR title with the wrong dash
-// is not one of these: it opens with an id, and stays refused as a typo.
-func TestATitleWithNoNumberIsNumberedByItsFile(t *testing.T) {
-	adr := parsedTools(t, strings.Replace(toolsSample, "# 3. Use DTO", "# Use DTO", 1), "avia.aviasupp")
-	if adr.ID != "aviasupp.0003" || adr.Number != 3 || adr.Title != "Use DTO" {
-		t.Errorf("id %q, number %d, title %q", adr.ID, adr.Number, adr.Title)
-	}
-
-	_, errs := parseAdr("docs/ADR/river.md", strings.Replace(toolsSample, "# 3. Use DTO", "# River", 1), defaults{})
-	if len(errs) == 0 || !strings.Contains(errs[0], "nothing numbers the record") {
-		t.Errorf("errors: %v", errs)
-	}
-}

package/plugins/extract-asyncapi/describe.go

@@ -1,19 +0,0 @@
-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-asyncapi",
-		Summary: "Reads an AsyncAPI document and answers with the channels a service publishes on and listens to.",
-		Phases:  []string{plugin.PhaseExtract},
-		Options: optionsSchema,
-	}
-}

package/plugins/extract-asyncapi/describe_test.go

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