@shortlink-org/portolan 0.1.0 → 0.2.0

package/plugins/extract-graphql/extract_test.go

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

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

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

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