@shortlink-org/portolan 0.1.0 → 0.2.1

package/plugins/extract-openapi/extract_test.go

@@ -1,545 +0,0 @@
-package main
-
-import (
-	"encoding/json"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/shortlink-org/portolan/catalog"
-	"github.com/shortlink-org/portolan/plugin"
-	"gopkg.in/yaml.v3"
-)
-
-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: "billing", Service: "invoices", Spec: "openapi.yaml"},
-	)
-	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 testDocument(t *testing.T, source string) *document {
-	t.Helper()
-	var root yaml.Node
-	if err := yaml.Unmarshal([]byte(source), &root); err != nil {
-		t.Fatal(err)
-	}
-	node := root.Content[0]
-	return &document{root: node, path: "test.yaml", cache: map[string]*document{}}
-}
-
-func provided(t *testing.T) []catalog.RpcService {
-	t.Helper()
-
-	return fragment(t).Contexts[0].Services[0].Provides
-}
-
-// A method is an object now, and every assertion below is about the names.
-func names(methods []catalog.RpcMethod) []string {
-	out := make([]string, 0, len(methods))
-	for _, method := range methods {
-		out = append(out, method.Name)
-	}
-
-	return out
-}
-
-// Tags organise operations within one OpenAPI contract. They must not split a
-// document into duplicate interfaces with duplicate message inventories.
-func TestTagsStayWithinOneService(t *testing.T) {
-	provides := provided(t)
-	if len(provides) != 1 {
-		t.Fatalf("provides = %d, want one contract", len(provides))
-	}
-	if provides[0].ID != "billing.v2" {
-		t.Errorf("interface = %q", provides[0].ID)
-	}
-	if got := strings.Join(names(provides[0].Methods), ","); got != "raiseInvoice,GET /v2/health" {
-		t.Errorf("methods = %q", got)
-	}
-}
-
-func TestSharedSchemaIsNotRepeatedAcrossTags(t *testing.T) {
-	doc := testDocument(t, `
-openapi: 3.0.3
-info: {title: shared, version: 1.0.0}
-paths:
-  /orders:
-    get:
-      tags: [orders]
-      operationId: listOrders
-      responses:
-        '200':
-          content:
-            application/json:
-              schema: {$ref: '#/components/schemas/Result'}
-  /refunds:
-    get:
-      tags: [refunds]
-      operationId: listRefunds
-      responses:
-        '200':
-          content:
-            application/json:
-              schema: {$ref: '#/components/schemas/Result'}
-components:
-  schemas:
-    Result: {type: object}
-`)
-
-	services := rpcServices(doc, "shared.v1", "test.yaml", &plugin.Builder{})
-	if len(services) != 1 || len(services[0].Methods) != 2 || len(services[0].Messages) != 1 {
-		t.Fatalf("contract = %+v", services)
-	}
-}
-
-// The id is the document's own title and major version, so it survives a patch
-// release without every id in the catalog changing.
-func TestApiIDFromTitleAndMajorVersion(t *testing.T) {
-	for _, p := range provided(t) {
-		if !strings.HasPrefix(p.ID, "billing.v2") {
-			t.Errorf("unexpected id %q", p.ID)
-		}
-	}
-}
-
-// A shared response is how a spec says "the same error body as everywhere
-// else". Not following it would document the endpoint as returning nothing
-// when it fails.
-func TestFollowsRefsThroughSharedResponses(t *testing.T) {
-	var names []string
-	for _, p := range provided(t) {
-		if p.ID != "billing.v2" {
-			continue
-		}
-		for _, message := range p.Messages {
-			names = append(names, message.Name)
-		}
-	}
-
-	// Line arrives through RaiseRequest, Error through the shared BadRequest.
-	want := "RaiseRequest,Invoice,Error,Line"
-	if strings.Join(names, ",") != want {
-		t.Errorf("messages = %v, want %s", names, want)
-	}
-}
-
-func TestFieldTypesAndOptionality(t *testing.T) {
-	var request *catalog.RpcMessage
-	for _, p := range provided(t) {
-		for i := range p.Messages {
-			if p.Messages[i].Name == "RaiseRequest" {
-				request = &p.Messages[i]
-			}
-		}
-	}
-	if request == nil {
-		t.Fatal("no RaiseRequest message")
-	}
-
-	fields := map[string]catalog.Field{}
-	for _, field := range request.Fields {
-		fields[field.Name] = field
-	}
-
-	if got := fields["customerId"].Type; got != "string (uuid)" {
-		t.Errorf("format belongs in the type, got %q", got)
-	}
-	if got := fields["customerId"].Doc; got != "Who is being billed." {
-		t.Errorf("a required field carries its description alone, got %q", got)
-	}
-	if got := fields["lines"].Type; got != "[]Line" {
-		t.Errorf("an array of refs, got %q", got)
-	}
-	// Which fields must be sent is the first thing a caller needs, and the
-	// catalog has nowhere else to put it.
-	if got := fields["lines"].Doc; !strings.HasPrefix(got, "Optional.") {
-		t.Errorf("an optional field should say so, got %q", got)
-	}
-}
-
-func TestComposedSchemasMapsEnumsAndNullableTypes(t *testing.T) {
-	doc := testDocument(t, `
-components:
-  schemas:
-    Base:
-      type: object
-      required: [id]
-      properties:
-        id: {type: string, format: uuid}
-    Account:
-      allOf:
-        - $ref: '#/components/schemas/Base'
-        - type: object
-          required: [labels]
-          properties:
-            labels:
-              type: object
-              additionalProperties: {type: string}
-            state:
-              type: string
-              enum: [active, disabled]
-            contact:
-              nullable: true
-              oneOf:
-                - {type: string, format: email}
-                - {type: string, format: phone}
-`)
-	account := child(doc.root, "components", "schemas", "Account")
-	fields := map[string]catalog.Field{}
-	for _, field := range schemaFields(doc, account) {
-		fields[field.Name] = field
-	}
-
-	if fields["id"].Type != "string (uuid)" || strings.HasPrefix(fields["id"].Doc, "Optional.") {
-		t.Errorf("allOf required field = %+v", fields["id"])
-	}
-	if fields["labels"].Type != "map[string]string" || strings.HasPrefix(fields["labels"].Doc, "Optional.") {
-		t.Errorf("map field = %+v", fields["labels"])
-	}
-	if fields["state"].Type != "string enum(active | disabled)" || !strings.HasPrefix(fields["state"].Doc, "Optional.") {
-		t.Errorf("enum field = %+v", fields["state"])
-	}
-	if fields["contact"].Type != "string (email) | string (phone) | null" {
-		t.Errorf("oneOf nullable field type = %q", fields["contact"].Type)
-	}
-}
-
-func TestDiscriminatorKeepsPolymorphicMessagesVisible(t *testing.T) {
-	doc := testDocument(t, `
-openapi: 3.1.0
-info: {title: animals, version: 1.0.0}
-paths:
-  /pets/{id}:
-    get:
-      operationId: getPet
-      responses:
-        '200':
-          content:
-            application/json:
-              schema: {$ref: '#/components/schemas/Pet'}
-components:
-  schemas:
-    Pet:
-      oneOf:
-        - {$ref: '#/components/schemas/Cat'}
-        - {$ref: '#/components/schemas/Dog'}
-      discriminator:
-        propertyName: kind
-        mapping:
-          feline: '#/components/schemas/Cat'
-    Cat:
-      type: object
-      required: [kind, lives]
-      properties:
-        kind: {type: string}
-        lives: {type: integer}
-    Dog:
-      type: object
-      required: [kind, good]
-      properties:
-        kind: {type: string}
-        good: {type: boolean}
-`)
-	services := rpcServices(doc, "animals.v1", "test.yaml", &plugin.Builder{})
-	if len(services) != 1 || len(services[0].Methods) != 1 {
-		t.Fatalf("services = %+v", services)
-	}
-	if got := services[0].Methods[0].Response; got != "Pet" {
-		t.Fatalf("response = %q, want Pet", got)
-	}
-
-	byName := map[string]catalog.RpcMessage{}
-	for _, message := range services[0].Messages {
-		byName[message.Name] = message
-	}
-	pet, ok := byName["Pet"]
-	if !ok || pet.Discriminator == nil {
-		t.Fatalf("Pet discriminator is missing: %+v", pet)
-	}
-	if pet.Discriminator.Property != "kind" {
-		t.Errorf("property = %q", pet.Discriminator.Property)
-	}
-	if len(pet.Discriminator.Variants) != 2 {
-		t.Fatalf("variants = %+v", pet.Discriminator.Variants)
-	}
-	if got := pet.Discriminator.Variants[0]; got.Value != "feline" || got.Message != "Cat" {
-		t.Errorf("mapped variant = %+v", got)
-	}
-	if got := pet.Discriminator.Variants[1]; got.Value != "Dog" || got.Message != "Dog" {
-		t.Errorf("implicit variant = %+v", got)
-	}
-	if _, ok := byName["Cat"]; !ok {
-		t.Error("Cat concrete message is missing")
-	}
-	if _, ok := byName["Dog"]; !ok {
-		t.Error("Dog concrete message is missing")
-	}
-}
-
-func TestRelativeExternalSchemaRefsAreLoaded(t *testing.T) {
-	dir := t.TempDir()
-	common := filepath.Join(dir, "common.yaml")
-	root := filepath.Join(dir, "openapi.yaml")
-	if err := os.WriteFile(common, []byte(`components:
-  schemas:
-    External:
-      type: object
-      required: [code]
-      properties:
-        code: {type: integer, format: int64}
-`), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(root, []byte(`openapi: 3.1.0
-info: {title: external, version: 1.0.0}
-paths:
-  /external:
-    get:
-      operationId: getExternal
-      responses:
-        '200':
-          content:
-            application/json:
-              schema: {$ref: './common.yaml#/components/schemas/External'}
-`), 0o600); err != nil {
-		t.Fatal(err)
-	}
-	doc, err := load(root)
-	if err != nil {
-		t.Fatal(err)
-	}
-	services := rpcServices(doc, "external.v1", root, &plugin.Builder{})
-	if len(services) != 1 || len(services[0].Messages) != 1 {
-		t.Fatalf("services = %+v", services)
-	}
-	message := services[0].Messages[0]
-	if message.Name != "External" || len(message.Fields) != 1 || message.Fields[0].Type != "integer (int64)" {
-		t.Errorf("external message = %+v", message)
-	}
-}
-
-// The fragment describes what the service answers and nothing else; the name
-// and readme belong to whichever source knows them.
-func TestFragmentClaimsNothingItDoesNotKnow(t *testing.T) {
-	service := fragment(t).Contexts[0].Services[0]
-
-	if service.Name != "" || service.Readme != "" || service.Repo != "" {
-		t.Errorf("the api fragment should not name the service: %+v", service)
-	}
-	if len(service.Aggregates) != 0 {
-		t.Error("the api fragment should carry no aggregates")
-	}
-}
-
-// What the operation sends and answers with. The document names both whenever
-// the body is a $ref; a success with no body at all is answered by its status,
-// because 204 is a real answer and an empty string reads as an unread one.
-func TestShapesOnEitherSide(t *testing.T) {
-	byName := map[string]catalog.RpcMethod{}
-	for _, p := range provided(t) {
-		for _, method := range p.Methods {
-			byName[method.Name] = method
-		}
-	}
-
-	raise, ok := byName["raiseInvoice"]
-	if !ok {
-		t.Fatal("no raiseInvoice")
-	}
-	if raise.Request != "RaiseRequest" || raise.Response != "Invoice" {
-		t.Errorf("raiseInvoice sends %q and returns %q", raise.Request, raise.Response)
-	}
-
-	health, ok := byName["GET /v2/health"]
-	if !ok {
-		t.Fatal("no health operation")
-	}
-	if health.Request != "" || health.Response != "200" {
-		t.Errorf("health sends %q and returns %q", health.Request, health.Response)
-	}
-}
-
-// The same document, read as a copy vendored from outside the estate: the
-// fragment carries no context and no service, only the external and what it
-// answers on, under the id the manifest gave it.
-func TestExternalCarriesNoService(t *testing.T) {
-	resp, err := extract(
-		plugin.Input{Root: "testdata", Commit: "abc1234", GeneratedAt: "2026-01-01T00:00:00Z"},
-		Options{External: "psp", ExternalName: "PSP", ExternalURL: "https://psp.example/docs", API: "psp.v1", Spec: "openapi.yaml"},
-	)
-	if err != nil {
-		t.Fatal(err)
-	}
-	var out catalog.Catalog
-	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
-		t.Fatal(err)
-	}
-	if len(out.Contexts) != 0 {
-		t.Errorf("an external's fragment names %d contexts", len(out.Contexts))
-	}
-	if len(out.Externals) != 1 {
-		t.Fatalf("externals = %+v", out.Externals)
-	}
-	ext := out.Externals[0]
-	if ext.ID != "psp" || ext.Slug != "psp" || ext.Name != "PSP" || ext.URL != "https://psp.example/docs" {
-		t.Errorf("external = %+v", ext)
-	}
-	var ids []string
-	for _, p := range ext.Provides {
-		ids = append(ids, p.ID)
-	}
-	if strings.Join(ids, ",") != "psp.v1" {
-		t.Errorf("interfaces = %v", ids)
-	}
-
-	// A dotted id would put the external inside a context nobody declared.
-	if _, err := extract(plugin.Input{Root: "testdata"}, Options{External: "shop.psp"}); err == nil {
-		t.Error("an external with a dot in its id was accepted")
-	}
-}
-
-// A Swagger 2.0 document keeps its schemas under definitions, sends its body
-// as a parameter and puts the response schema straight on the response. A
-// generator that still writes 2.0 - swag, for one - documents a service
-// exactly as well as one that writes 3.
-func TestSwagger2DefinitionsAndBodyParameters(t *testing.T) {
-	resp, err := extract(
-		plugin.Input{Root: "testdata/swagger2", Commit: "abc1234", GeneratedAt: "2026-01-01T00:00:00Z"},
-		Options{Context: "avia", Service: "aviasupp", Spec: "swagger.yaml"},
-	)
-	if err != nil {
-		t.Fatal(err)
-	}
-	var out catalog.Catalog
-	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
-		t.Fatal(err)
-	}
-
-	byName := map[string]catalog.RpcMethod{}
-	shapes := map[string][]string{}
-	for _, p := range out.Contexts[0].Services[0].Provides {
-		for _, method := range p.Methods {
-			byName[method.Name] = method
-		}
-		for _, message := range p.Messages {
-			var fields []string
-			for _, field := range message.Fields {
-				fields = append(fields, field.Name+" "+field.Type)
-			}
-			shapes[message.Name] = fields
-		}
-	}
-
-	book, ok := byName["POST /book"]
-	if !ok {
-		t.Fatalf("no POST /book among %v", byName)
-	}
-	if book.Request != "book.Request" || book.Response != "book.Response" {
-		t.Errorf("book sends %q and returns %q", book.Request, book.Response)
-	}
-
-	// The body parameter is inherited from the path item, and a list of a
-	// definition is that definition with brackets.
-	search, ok := byName["search"]
-	if !ok {
-		t.Fatalf("no search among %v", byName)
-	}
-	if search.Request != "search.Request" || search.Response != "search.Offer[]" {
-		t.Errorf("search sends %q and returns %q", search.Request, search.Response)
-	}
-
-	if got := strings.Join(shapes["book.Request"], ", "); got != "offer_id string, passengers []book.Passenger" {
-		t.Errorf("book.Request = %q", got)
-	}
-	if _, ok := shapes["book.Passenger"]; !ok {
-		t.Errorf("book.Passenger, reached through book.Request, is not among the messages: %v", shapes)
-	}
-	if _, ok := shapes["search.Offer"]; !ok {
-		t.Errorf("search.Offer, the response item, is not among the messages: %v", shapes)
-	}
-}
-
-// Nothing named: the tree says which documents this service implements and
-// which it calls. A server generated from a document means provides; a client
-// generated from one means a system outside the estate, named by the
-// document's own title, unless the manifest says the api is one of ours. A
-// document with neither beside it is reported and left alone.
-func TestATreeSaysWhatIsImplementedAndWhatIsCalled(t *testing.T) {
-	read := func(opts Options) (catalog.Catalog, plugin.Response) {
-		t.Helper()
-		opts.Context, opts.Service = "avia", "aviasupp"
-		resp, err := extract(plugin.Input{Root: "testdata/discover", Commit: "abc1234", GeneratedAt: "2026-01-01T00:00:00Z"}, opts)
-		if err != nil {
-			t.Fatal(err)
-		}
-		var out catalog.Catalog
-		if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
-			t.Fatal(err)
-		}
-		return out, resp
-	}
-
-	out, resp := read(Options{Peers: map[string]string{"partner-api.v2": "shop.partner"}})
-
-	var provided []string
-	for _, p := range out.Contexts[0].Services[0].Provides {
-		provided = append(provided, p.ID+" from "+p.Source)
-	}
-	if strings.Join(provided, ", ") != "aviasupp.v1 from testdata/discover/docs/swagger.yaml" {
-		t.Errorf("provides = %v", provided)
-	}
-
-	if len(out.Externals) != 1 {
-		t.Fatalf("externals = %+v", out.Externals)
-	}
-	acme := out.Externals[0]
-	if acme.ID != "acme-flights" || acme.Slug != "acme-flights" || acme.Name != "Acme Flights API" || acme.Summary != "Flights and ancillaries from Acme." || acme.URL != "https://developer.acme.example/flights" {
-		t.Errorf("external = %+v", acme)
-	}
-	if len(acme.Provides) != 1 || acme.Provides[0].ID != "acme-flights-api.v1" {
-		t.Errorf("acme provides %+v", acme.Provides)
-	}
-
-	warned := func(substring string) bool {
-		for _, w := range resp.Warnings() {
-			if strings.Contains(w.Message, substring) {
-				return true
-			}
-		}
-		return false
-	}
-	if !warned("found testdata/discover/internal/stray/openapi.yaml, and nothing beside it says") {
-		t.Errorf("the stray document was not reported; warnings = %+v", resp.Warnings())
-	}
-	if !warned("nameless/client/openapi.yaml is called from here and its document has no title") {
-		t.Errorf("the nameless document was not reported; warnings = %+v", resp.Warnings())
-	}
-
-	// The manifest may name the system itself; and a called document whose
-	// api no peers line claims is a system outside the estate too.
-	out, _ = read(Options{Externals: map[string]string{"acme-flights-api.v1": "acme"}})
-	var ids []string
-	for _, e := range out.Externals {
-		ids = append(ids, e.ID)
-	}
-	if strings.Join(ids, ",") != "acme,partner" {
-		t.Errorf("externals = %v", ids)
-	}
-}

package/plugins/extract-openapi/main.go

@@ -1,75 +0,0 @@
-// Package main is portolan-extract-openapi: an OpenAPI document in, a catalog
-// fragment out.
-//
-// It describes one aspect of a service - what it answers - and nothing else.
-// The aggregates come from a different extractor reading a different part of
-// the tree, 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 an OpenAPI
-// document does not say about the estate it belongs to.
-type Options struct {
-	Context string `json:"context"`
-	Service string `json:"service"`
-
-	// Spec is the document, relative to the input root. Left out, the
-	// extractor walks the tree for every document and reads what sits beside
-	// each one: a server generated from it means this service implements it,
-	// a client generated from it means this service calls it, and a called
-	// document names a system outside the estate unless `peers` says the api
-	// is one of ours.
-	Spec string `json:"spec,omitempty"`
-
-	// Peers says which called documents are ours, as the api id to the
-	// service that implements it: {"auth.v1": "auth.auth"}. A called document
-	// whose api is named here is that service's to describe, and is skipped.
-	Peers map[string]string `json:"peers,omitempty"`
-
-	// Externals names a called document's system when the name its title
-	// would give is not the one wanted, as the api id to the external's bare
-	// id: {"stripe.v1": "stripe"}.
-	Externals map[string]string `json:"externals,omitempty"`
-
-	// API prefixes the ids of the rpc services this produces. Left out, it is
-	// built from the document's title and major version - `auth` 1.0.0 gives
-	// `auth.v1`, and a tag called `users` gives `auth.v1.Users`.
-	API string `json:"api,omitempty"`
-
-	// External names a system outside the estate the document belongs to,
-	// when it is not one of ours: the copy vendored beside an adapter, read
-	// for what the third party answers on. Set, the fragment carries no
-	// context and no service, only the external, and `context` and `service`
-	// are not read.
-	External        string `json:"external,omitempty"`
-	ExternalName    string `json:"externalName,omitempty"`
-	ExternalSummary string `json:"externalSummary,omitempty"`
-	ExternalURL     string `json:"externalUrl,omitempty"`
-
-	Out string `json:"out,omitempty"`
-}
-
-func main() {
-	if err := run(os.Stdin, os.Stdout); err != nil {
-		fmt.Fprintln(os.Stderr, "portolan-extract-openapi:", 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)
-	})
-}