@shortlink-org/portolan 0.1.0

package/plugins/extract-graphql/extract_test.go

@@ -0,0 +1,256 @@
+package main
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+func fragment(t *testing.T) catalog.Catalog {
+	t.Helper()
+
+	resp, err := extract(
+		plugin.Input{Root: "testdata", Commit: "abc1234", GeneratedAt: "2026-01-01T00:00:00Z"},
+		Options{Context: "storefront", Service: "bff", Schema: "schema", API: "storefront.v1"},
+	)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(resp.Files) != 1 {
+		t.Fatalf("expected one fragment, got %d files", len(resp.Files))
+	}
+
+	var out catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
+		t.Fatal(err)
+	}
+
+	return out
+}
+
+func provided(t *testing.T) []catalog.RpcService {
+	t.Helper()
+
+	return fragment(t).Contexts[0].Services[0].Provides
+}
+
+func interfaceNamed(t *testing.T, id string) catalog.RpcService {
+	t.Helper()
+
+	for _, p := range provided(t) {
+		if p.ID == id {
+			return p
+		}
+	}
+	t.Fatalf("no interface %q in the fragment", id)
+
+	return catalog.RpcService{}
+}
+
+func method(t *testing.T, id, name string) catalog.RpcMethod {
+	t.Helper()
+
+	for _, m := range interfaceNamed(t, id).Methods {
+		if m.Name == name {
+			return m
+		}
+	}
+	t.Fatalf("no method %q on %q", name, id)
+
+	return catalog.RpcMethod{}
+}
+
+func message(t *testing.T, id, name string) catalog.RpcMessage {
+	t.Helper()
+
+	for _, m := range interfaceNamed(t, id).Messages {
+		if m.Name == name {
+			return m
+		}
+	}
+	t.Fatalf("no message %q on %q", name, id)
+
+	return catalog.RpcMessage{}
+}
+
+// A module is how a schema's author says "these fields belong together", the
+// way a tag is in an OpenAPI document - and unlike a tag it is a file, so the
+// interface can point at something a reader can open.
+func TestModulesBecomeInterfaces(t *testing.T) {
+	got := map[string]string{}
+	for _, p := range provided(t) {
+		got[p.ID] = p.Source
+	}
+
+	want := map[string]string{
+		"storefront.v1.Basket": "testdata/schema/basket/schema.graphql",
+		"storefront.v1.Order":  "testdata/schema/order/schema.graphql",
+	}
+	for id, source := range want {
+		if got[id] != source {
+			t.Errorf("%s reads %q, want %q", id, got[id], source)
+		}
+	}
+	if len(got) != len(want) {
+		t.Errorf("declared %d interfaces, want %d: %v", len(got), len(want), got)
+	}
+}
+
+// The generator writes the whole schema out again beside the modules it read.
+// Reading that copy would give the estate a module nobody wrote, holding every
+// field a second time.
+func TestTheGeneratedCopyIsNotAModule(t *testing.T) {
+	for _, p := range provided(t) {
+		if strings.Contains(p.Source, ".generated.") {
+			t.Errorf("%s was read out of the generated copy %s", p.ID, p.Source)
+		}
+	}
+}
+
+// A field is named by the operation it belongs to. Two operations may each
+// have a `basket` field and they are not the same endpoint.
+func TestMethodsAreNamedByOperation(t *testing.T) {
+	var names []string
+	for _, m := range interfaceNamed(t, "storefront.v1.Basket").Methods {
+		names = append(names, m.Name)
+	}
+
+	want := []string{"Query.basket", "Query.legacyBasket", "Mutation.addItem"}
+	if len(names) != len(want) {
+		t.Fatalf("methods are %v, want %v", names, want)
+	}
+	for i := range want {
+		if names[i] != want[i] {
+			t.Errorf("method %d is %q, want %q", i, names[i], want[i])
+		}
+	}
+}
+
+// A subscription keeps answering. Drawn as a call it would be a lie about how
+// the two ends are coupled, which is what Streaming exists to prevent.
+func TestSubscriptionsAreServerStreams(t *testing.T) {
+	if got := method(t, "storefront.v1.Order", "Subscription.orderStatus").Streaming; got != catalog.StreamingServer {
+		t.Errorf("streaming is %q, want %q", got, catalog.StreamingServer)
+	}
+	if got := method(t, "storefront.v1.Basket", "Query.basket").Streaming; got != "" {
+		t.Errorf("a query is streaming %q, want unary", got)
+	}
+}
+
+// A field whose whole input is one input object is already named by the
+// schema; a field with loose arguments is not, so a name is made and the
+// arguments become its fields.
+func TestArgumentsAreNamedOnceAndInventedOtherwise(t *testing.T) {
+	if got := method(t, "storefront.v1.Basket", "Mutation.addItem").Request; got != "AddItemInput" {
+		t.Errorf("request is %q, want the input object AddItemInput", got)
+	}
+
+	if got := method(t, "storefront.v1.Order", "Query.order").Request; got != "QueryOrderArgs" {
+		t.Errorf("request is %q, want QueryOrderArgs", got)
+	}
+
+	args := message(t, "storefront.v1.Order", "QueryOrderArgs")
+	if len(args.Fields) != 2 || args.Fields[0].Name != "id" || args.Fields[1].Name != "at" {
+		t.Fatalf("QueryOrderArgs holds %+v, want id and at", args.Fields)
+	}
+	// `at` is nullable, and the rest of the catalog says that in prose.
+	if args.Fields[1].Doc != "Optional." {
+		t.Errorf("the nullable argument reads %q, want it marked optional", args.Fields[1].Doc)
+	}
+}
+
+// A response names a shape, and the shapes it names are walked until nothing
+// new is reached: a reader who has to open the schema to find out what a Line
+// holds has been given a worse document than the schema.
+func TestMessagesFollowWhatTheyReach(t *testing.T) {
+	var names []string
+	for _, m := range interfaceNamed(t, "storefront.v1.Basket").Messages {
+		names = append(names, m.Name)
+	}
+
+	for _, want := range []string{"Basket", "Line", "Money", "AddItemInput"} {
+		found := false
+		for _, name := range names {
+			found = found || name == want
+		}
+		if !found {
+			t.Errorf("%s is reachable from the basket module and is not in %v", want, names)
+		}
+	}
+}
+
+// A list is spelled the way every other extractor here spells one, and an enum
+// carries its values: a status whose values are three clicks away is a status
+// nobody reads.
+func TestTypesAreSpelledLikeTheRestOfTheCatalog(t *testing.T) {
+	basket := message(t, "storefront.v1.Basket", "Basket")
+	byName := map[string]catalog.Field{}
+	for _, f := range basket.Fields {
+		byName[f.Name] = f
+	}
+
+	if got := byName["lines"].Type; got != "[]Line" {
+		t.Errorf("lines is %q, want []Line", got)
+	}
+	if got := byName["quote"].Doc; got != "Optional. Nothing has been priced yet when the basket is empty." {
+		t.Errorf("the nullable field reads %q", got)
+	}
+
+	order := message(t, "storefront.v1.Order", "Order")
+	for _, f := range order.Fields {
+		if f.Name == "status" && f.Type != "OrderStatus enum(PLACED | CONFIRMED | CANCELLED)" {
+			t.Errorf("status is %q, want the enum and its values", f.Type)
+		}
+	}
+}
+
+// GraphQL is polymorphic in two ways and answers both of them with the same
+// field, which is the one a client would select.
+func TestUnionsDiscriminateOnTypename(t *testing.T) {
+	result := message(t, "storefront.v1.Order", "OrderResult")
+	if result.Discriminator == nil {
+		t.Fatal("a union came back with no discriminator")
+	}
+	if result.Discriminator.Property != "__typename" {
+		t.Errorf("discriminates on %q, want __typename", result.Discriminator.Property)
+	}
+
+	var variants []string
+	for _, v := range result.Discriminator.Variants {
+		variants = append(variants, v.Message)
+	}
+	if len(variants) != 2 || variants[0] != "Order" || variants[1] != "OrderNotFound" {
+		t.Errorf("variants are %v, want Order and OrderNotFound", variants)
+	}
+}
+
+// A deprecated field is reported deprecated, and its reason is prose the
+// reader gets to see.
+func TestDeprecationSurvives(t *testing.T) {
+	m := method(t, "storefront.v1.Basket", "Query.legacyBasket")
+	if !m.Deprecated {
+		t.Error("the deprecated field is not marked deprecated")
+	}
+	if m.Doc != "Deprecated: Ask for `basket` instead." {
+		t.Errorf("doc is %q, want the deprecation reason", m.Doc)
+	}
+}
+
+// The same schema read twice is the same fragment. Everything that came out of
+// a map is sorted, and nothing reads a clock.
+func TestExtractionIsDeterministic(t *testing.T) {
+	first, err := json.Marshal(fragment(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	second, err := json.Marshal(fragment(t))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(first) != string(second) {
+		t.Error("two runs over the same schema produced different fragments")
+	}
+}

package/plugins/extract-graphql/ids.go

@@ -0,0 +1,49 @@
+package main
+
+// What a schema's parts are called in the catalog.
+//
+// Two readers have to agree on these. This one reads the SDL and says what a
+// service provides; `extract-ts` reads the resolvers beside it and says what
+// each field goes on to call, and a flow step that named a field differently
+// from the method it lands on would never meet it. The spelling is written
+// out twice because the two are in different languages; `extract-ts/graphql.ts`
+// is the other copy.
+
+import "strings"
+
+// interfaceID is the interface a module's root fields land in: the api and the
+// module, `storefront.v1.Basket`. A schema in one file has no module to name,
+// and its fields land on the api itself.
+func interfaceID(api, module string) string {
+	if module == "" {
+		return api
+	}
+
+	return api + "." + title(module)
+}
+
+// methodName is a root field by the operation it belongs to: `Query.basket`.
+// GraphQL has no other name for it - two operations may each have a `basket`
+// field, and they are not the same endpoint.
+func methodName(root, field string) string { return root + "." + field }
+
+// argsMessage names the shape a field's arguments make when they are not
+// already one input object: `Query.basket(id: ID!)` gives `QueryBasketArgs`.
+// The name is the one graphql-codegen generates for the same thing, so a
+// reader who has the generated types open recognises it.
+func argsMessage(root, field string) string { return root + title(field) + "Args" }
+
+// title is the human form of a module name: `basket` becomes Basket,
+// `order_status` becomes OrderStatus.
+func title(name string) string {
+	var b strings.Builder
+	for _, word := range strings.FieldsFunc(name, func(r rune) bool { return r == '_' || r == '-' || r == ' ' || r == '.' }) {
+		runes := []rune(word)
+		if runes[0] >= 'a' && runes[0] <= 'z' {
+			runes[0] = runes[0] - 'a' + 'A'
+		}
+		b.WriteString(string(runes))
+	}
+
+	return b.String()
+}

package/plugins/extract-graphql/lex.go

@@ -0,0 +1,237 @@
+package main
+
+// The tokens of a GraphQL SDL document, and the descriptions attached to them.
+//
+// A schema documents itself in strings rather than in comments: `# ...` is
+// thrown away by every reader, and the prose a client is meant to see sits in
+// a string literal directly above the thing it describes. So the lexer keeps
+// string tokens as tokens - the parser decides which of them are descriptions -
+// and drops comments on the floor, which is the opposite of what the proto
+// lexer beside it has to do.
+
+import (
+	"fmt"
+	"strings"
+	"unicode"
+	"unicode/utf8"
+)
+
+type kind int
+
+const (
+	tokEOF kind = iota
+	tokName
+	tokString
+	tokNumber
+	tokPunct
+)
+
+type token struct {
+	kind kind
+	text string
+	line int
+}
+
+func (t token) is(text string) bool {
+	return (t.kind == tokPunct || t.kind == tokName) && t.text == text
+}
+
+type lexer struct {
+	src  string
+	pos  int
+	line int
+}
+
+func lex(src string) ([]token, error) {
+	l := &lexer{src: strings.TrimPrefix(src, "\ufeff"), line: 1}
+
+	var out []token
+	for {
+		tok, err := l.next()
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, tok)
+		if tok.kind == tokEOF {
+			return out, nil
+		}
+	}
+}
+
+func (l *lexer) next() (token, error) {
+	for {
+		l.skipIgnored()
+		if l.pos >= len(l.src) {
+			return token{kind: tokEOF, line: l.line}, nil
+		}
+
+		c := l.src[l.pos]
+		switch {
+		case c == '#':
+			l.lineComment()
+			continue
+		case c == '"':
+			return l.stringLiteral()
+		case c == '_' || isLetter(c):
+			return l.name(), nil
+		case c == '-' || isDigit(c):
+			return l.number(), nil
+		}
+
+		// `...` is one token; every other punctuator is one byte. Nothing else
+		// is legal, and a document that reaches here is one no server would
+		// serve either.
+		if strings.HasPrefix(l.src[l.pos:], "...") {
+			tok := token{kind: tokPunct, text: "...", line: l.line}
+			l.pos += 3
+			return tok, nil
+		}
+		if strings.ContainsRune("!$&()::=@[]{|}", rune(c)) {
+			tok := token{kind: tokPunct, text: string(c), line: l.line}
+			l.pos++
+			return tok, nil
+		}
+
+		return token{}, fmt.Errorf("line %d: %q is not a graphql token", l.line, string(c))
+	}
+}
+
+// skipIgnored eats whitespace and the commas GraphQL treats as whitespace.
+func (l *lexer) skipIgnored() {
+	for l.pos < len(l.src) {
+		switch l.src[l.pos] {
+		case '\n':
+			l.line++
+			l.pos++
+		case ' ', '\t', '\r', ',':
+			l.pos++
+		default:
+			return
+		}
+	}
+}
+
+func (l *lexer) lineComment() {
+	for l.pos < len(l.src) && l.src[l.pos] != '\n' {
+		l.pos++
+	}
+}
+
+func (l *lexer) name() token {
+	start := l.pos
+	for l.pos < len(l.src) && (isLetter(l.src[l.pos]) || isDigit(l.src[l.pos]) || l.src[l.pos] == '_') {
+		l.pos++
+	}
+
+	return token{kind: tokName, text: l.src[start:l.pos], line: l.line}
+}
+
+// number is lexed only so a default value can be stepped over. Nothing in the
+// catalog is interested in what it says.
+func (l *lexer) number() token {
+	start := l.pos
+	l.pos++
+	for l.pos < len(l.src) && (isDigit(l.src[l.pos]) || strings.ContainsRune(".eE+-", rune(l.src[l.pos]))) {
+		l.pos++
+	}
+
+	return token{kind: tokNumber, text: l.src[start:l.pos], line: l.line}
+}
+
+func (l *lexer) stringLiteral() (token, error) {
+	line := l.line
+	if strings.HasPrefix(l.src[l.pos:], `"""`) {
+		l.pos += 3
+		start := l.pos
+		for {
+			if l.pos >= len(l.src) {
+				return token{}, fmt.Errorf("line %d: a block string is never closed", line)
+			}
+			if strings.HasPrefix(l.src[l.pos:], `"""`) && (l.pos == start || l.src[l.pos-1] != '\\') {
+				text := l.src[start:l.pos]
+				l.line += strings.Count(text, "\n")
+				l.pos += 3
+				return token{kind: tokString, text: blockString(text), line: line}, nil
+			}
+			l.pos++
+		}
+	}
+
+	l.pos++
+	var b strings.Builder
+	for {
+		if l.pos >= len(l.src) || l.src[l.pos] == '\n' {
+			return token{}, fmt.Errorf("line %d: a string is never closed", line)
+		}
+		c := l.src[l.pos]
+		if c == '"' {
+			l.pos++
+			return token{kind: tokString, text: b.String(), line: line}, nil
+		}
+		if c == '\\' && l.pos+1 < len(l.src) {
+			l.pos++
+			switch l.src[l.pos] {
+			case 'n':
+				b.WriteByte('\n')
+			case 't':
+				b.WriteByte('\t')
+			case 'u':
+				if l.pos+4 < len(l.src) {
+					var r rune
+					if _, err := fmt.Sscanf(l.src[l.pos+1:l.pos+5], "%04x", &r); err == nil {
+						b.WriteRune(r)
+						l.pos += 4
+					}
+				}
+			default:
+				b.WriteByte(l.src[l.pos])
+			}
+			l.pos++
+			continue
+		}
+		r, size := utf8.DecodeRuneInString(l.src[l.pos:])
+		b.WriteRune(r)
+		l.pos += size
+	}
+}
+
+// blockString applies the indentation rules the spec gives for `"""` strings:
+// the common indent of every line after the first is removed, and blank lines
+// at either end go with it. Without this every description in the catalog
+// would carry the indentation of the schema file it was written in.
+func blockString(raw string) string {
+	lines := strings.Split(strings.ReplaceAll(raw, "\r\n", "\n"), "\n")
+
+	indent := -1
+	for _, line := range lines[1:] {
+		trimmed := strings.TrimLeft(line, " \t")
+		if trimmed == "" {
+			continue
+		}
+		if width := len(line) - len(trimmed); indent < 0 || width < indent {
+			indent = width
+		}
+	}
+	if indent > 0 {
+		for i, line := range lines[1:] {
+			if len(line) >= indent {
+				lines[i+1] = line[indent:]
+			} else {
+				lines[i+1] = strings.TrimLeft(line, " \t")
+			}
+		}
+	}
+
+	for len(lines) > 0 && strings.TrimSpace(lines[0]) == "" {
+		lines = lines[1:]
+	}
+	for len(lines) > 0 && strings.TrimSpace(lines[len(lines)-1]) == "" {
+		lines = lines[:len(lines)-1]
+	}
+
+	return strings.Join(lines, "\n")
+}
+
+func isLetter(c byte) bool { return unicode.IsLetter(rune(c)) && c < utf8.RuneSelf }
+
+func isDigit(c byte) bool { return c >= '0' && c <= '9' }

package/plugins/extract-graphql/main.go

@@ -0,0 +1,51 @@
+// Package main is portolan-extract-graphql: a GraphQL schema in, a catalog
+// fragment out.
+//
+// It describes one aspect of a service - what a client may ask it for - and
+// nothing else. Who answers underneath is a different fact, read by whichever
+// extractor reads the resolvers, and the two meet in the merge. Neither knows
+// the other exists, which is the whole reason each of them stays small.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// Options are what the manifest tells the extractor: the things a schema does
+// not say about the estate it belongs to.
+type Options struct {
+	Context string `json:"context"`
+	Service string `json:"service"`
+
+	// Schema is the document or the directory of documents, relative to the
+	// input root. Left out, the extractor looks for them.
+	Schema string `json:"schema,omitempty"`
+
+	// API prefixes the ids of the interfaces this produces. Left out, it is
+	// the service and a major version - `bff` gives `bff.v1`, and a module
+	// called `basket` gives `bff.v1.Basket`.
+	API string `json:"api,omitempty"`
+
+	Out string `json:"out,omitempty"`
+}
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-extract-graphql:", 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-graphql/options.schema.json

@@ -0,0 +1,31 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context that owns the service this schema belongs to. Defaults to the name of the input directory.",
+      "examples": ["storefront"]
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the service the schema describes. Defaults to the name of the input directory.",
+      "examples": ["bff"]
+    },
+    "schema": {
+      "type": "string",
+      "description": "The schema, relative to the input root: one .graphql document, or a directory of them read together. Left out, the extractor looks for them.",
+      "examples": ["src/schema"]
+    },
+    "api": {
+      "type": "string",
+      "description": "Prefix for the ids of the interfaces this produces. Left out, it is the service and a major version: bff gives bff.v1, and a module called basket gives bff.v1.Basket.",
+      "examples": ["storefront.v1"]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory.",
+      "default": "graphql.json"
+    }
+  }
+}