@shortlink-org/portolan 0.1.0 → 0.2.0

package/internal/wsdl/parse_test.go

@@ -1,133 +0,0 @@
-package wsdl
-
-import (
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-)
-
-func writeFixture(t *testing.T, root, name, contents string) {
-	t.Helper()
-	path := filepath.Join(root, name)
-	if err := os.MkdirAll(filepath.Dir(path), 0o755); err != nil {
-		t.Fatal(err)
-	}
-	if err := os.WriteFile(path, []byte(contents), 0o644); err != nil {
-		t.Fatal(err)
-	}
-}
-
-func TestReadJoinsImportedPortTypeBindingAndSchema(t *testing.T) {
-	root := t.TempDir()
-	writeFixture(t, root, "types.xsd", `
-<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:booking" xmlns:tns="urn:booking">
-  <xsd:complexType name="CancelRequestType">
-    <xsd:sequence>
-      <xsd:element name="bookingId" type="xsd:string"/>
-      <xsd:element name="passengerIds" type="xsd:string" maxOccurs="unbounded"/>
-    </xsd:sequence>
-  </xsd:complexType>
-  <xsd:element name="CancelRequest" type="tns:CancelRequestType"/>
-  <xsd:element name="CancelResponse">
-    <xsd:complexType><xsd:sequence><xsd:element name="accepted" type="xsd:boolean"/></xsd:sequence></xsd:complexType>
-  </xsd:element>
-</xsd:schema>`)
-	writeFixture(t, root, "contract.wsdl", `
-<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:tns="urn:booking" targetNamespace="urn:booking">
-  <wsdl:types><xsd:schema targetNamespace="urn:booking"><xsd:import namespace="urn:booking" schemaLocation="types.xsd"/></xsd:schema></wsdl:types>
-  <wsdl:message name="CancelRequestMessage"><wsdl:part name="body" element="tns:CancelRequest"/></wsdl:message>
-  <wsdl:message name="CancelResponseMessage"><wsdl:part name="body" element="tns:CancelResponse"/></wsdl:message>
-  <wsdl:message name="BookingFault"><wsdl:part name="reason" type="xsd:string"/></wsdl:message>
-  <wsdl:portType name="BookingPortType">
-    <wsdl:operation name="CancelBooking">
-      <wsdl:documentation>Cancels a booking.</wsdl:documentation>
-      <wsdl:input message="tns:CancelRequestMessage"/>
-      <wsdl:output message="tns:CancelResponseMessage"/>
-      <wsdl:fault name="BookingFault" message="tns:BookingFault"/>
-    </wsdl:operation>
-  </wsdl:portType>
-</wsdl:definitions>`)
-	writeFixture(t, root, "service.wsdl", `
-<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:soap12="http://schemas.xmlsoap.org/wsdl/soap12/" xmlns:tns="urn:booking" targetNamespace="urn:booking" name="BookingDefinitions">
-  <wsdl:import namespace="urn:booking" location="contract.wsdl"/>
-  <wsdl:binding name="BookingBinding" type="tns:BookingPortType">
-    <soap12:binding style="document" transport="http://schemas.xmlsoap.org/soap/http"/>
-    <wsdl:operation name="CancelBooking">
-      <soap12:operation soapAction="urn:booking:cancel"/>
-      <wsdl:input><soap12:body use="literal"/><soap12:header message="tns:BookingFault" part="reason" use="literal"/></wsdl:input>
-    </wsdl:operation>
-  </wsdl:binding>
-  <wsdl:binding name="BookingBinding11" type="tns:BookingPortType">
-    <soap:binding style="rpc" transport="http://schemas.xmlsoap.org/soap/http"/>
-    <wsdl:operation name="CancelBooking"><soap:operation soapAction="urn:booking:cancel:v1"/></wsdl:operation>
-  </wsdl:binding>
-  <wsdl:service name="BookingService">
-    <wsdl:documentation>Booking supplier API.</wsdl:documentation>
-    <wsdl:port name="BookingPort" binding="tns:BookingBinding"><soap12:address location="https://booking.example/soap"/></wsdl:port>
-    <wsdl:port name="BookingPort11" binding="tns:BookingBinding11"><soap:address location="https://booking.example/soap/v1"/></wsdl:port>
-  </wsdl:service>
-</wsdl:definitions>`)
-
-	result, err := Read(root, "service.wsdl")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(result.Contracts) != 1 {
-		t.Fatalf("contracts = %+v", result.Contracts)
-	}
-	contract := result.Contracts[0]
-	if contract.Name != "BookingService" || contract.Summary != "Booking supplier API." || contract.Source != "service.wsdl" {
-		t.Fatalf("contract = %+v", contract)
-	}
-	if len(contract.Interfaces) != 2 {
-		t.Fatalf("interfaces = %+v", contract.Interfaces)
-	}
-	var iface Interface
-	for _, candidate := range contract.Interfaces {
-		if candidate.Name == "BookingPort" {
-			iface = candidate
-		}
-	}
-	if iface.Name != "BookingPort" || iface.PortType != "BookingPortType" || iface.Binding != "BookingBinding" || iface.Version != "1.2" || iface.Style != "document" || iface.Endpoint != "https://booking.example/soap" {
-		t.Fatalf("interface = %+v", iface)
-	}
-	if len(iface.Operations) != 1 {
-		t.Fatalf("operations = %+v", iface.Operations)
-	}
-	op := iface.Operations[0]
-	if op.Action != "urn:booking:cancel" || op.Request != "CancelRequestMessage" || op.Response != "CancelResponseMessage" || strings.Join(op.Faults, ",") != "BookingFault" || strings.Join(op.Headers, ",") != "BookingFault.reason" {
-		t.Fatalf("operation = %+v", op)
-	}
-	messages := map[string]Message{}
-	for _, message := range iface.Messages {
-		messages[message.Name] = message
-	}
-	request := messages["CancelRequestMessage"]
-	if len(request.Fields) != 2 || request.Fields[0].Name != "bookingId" || request.Fields[0].Type != "string" || request.Fields[1].Type != "string[]" {
-		t.Fatalf("request = %+v", request)
-	}
-	response := messages["CancelResponseMessage"]
-	if len(response.Fields) != 1 || response.Fields[0].Name != "accepted" || response.Fields[0].Type != "boolean" {
-		t.Fatalf("response = %+v", response)
-	}
-}
-
-func TestRemoteImportsAreWarningsAndNeverFetched(t *testing.T) {
-	root := t.TempDir()
-	writeFixture(t, root, "service.wsdl", `
-<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" targetNamespace="urn:local">
-  <import namespace="urn:remote" location="https://example.invalid/remote.wsdl"/>
-  <portType name="Local"><operation name="Ping"/></portType>
-</definitions>`)
-	result, err := Read(root, "service.wsdl")
-	if err != nil {
-		t.Fatal(err)
-	}
-	if len(result.Warnings) != 1 || !strings.Contains(result.Warnings[0], "remote import") {
-		t.Fatalf("warnings = %v", result.Warnings)
-	}
-	if len(result.Contracts) != 1 || len(result.Contracts[0].Interfaces) != 1 {
-		t.Fatalf("contracts = %+v", result.Contracts)
-	}
-}

package/plugin/describe.go

@@ -1,107 +0,0 @@
-// Describing a plugin: what it is called, where it belongs in a run, and what
-// it can be told.
-//
-// The options a plugin takes are facts the source does not carry - which
-// bounded context a Go module belongs to, whose proto package a client calls.
-// Only the plugin knows them, and until it could say so the manifest was a
-// file you wrote by reading somebody's struct. A misspelled key was silently
-// dropped, because that is what encoding/json does with a field it does not
-// recognise.
-//
-// So a plugin answers a second question now. The schema it hands back is
-// composed into schema/portolan.schema.json, which an editor reads while the
-// manifest is being written and the host checks before it runs anything.
-
-package plugin
-
-import (
-	"encoding/json"
-	"fmt"
-	"io"
-)
-
-// KindDescribe asks a plugin what it is rather than asking it to work.
-const KindDescribe = "describe"
-
-// Phases a step can be declared under in the manifest. A plugin names the ones
-// it belongs in, which is what stops the schema from offering an extractor
-// where a renderer goes.
-const (
-	PhaseExtract  = "extract"
-	PhaseVerify   = "verify"
-	PhaseGenerate = "generate"
-)
-
-// Descriptor is a plugin's answer to KindDescribe.
-type Descriptor struct {
-	// Name is what the plugin calls itself. The manifest is free to declare it
-	// under another name - the schema is keyed by the declared one - so this is
-	// for the reader, not for lookup.
-	Name string `json:"name"`
-
-	// Summary is one line, and it is the line an editor shows beside the step.
-	Summary string `json:"summary,omitempty"`
-
-	// Phases are the manifest sections this plugin belongs in.
-	Phases []string `json:"phases"`
-
-	// Options is a JSON Schema for what the manifest may pass in `options`.
-	// It must close itself with `additionalProperties: false`: the misspelled
-	// key is the error worth catching, and a schema that accepts anything
-	// catches nothing.
-	Options json.RawMessage `json:"options,omitempty"`
-}
-
-// Serve reads one request and writes one response - the whole of a plugin's
-// main, apart from the work itself.
-//
-// Every plugin had this loop written out, and each copy had to remember the
-// describe branch once there was one. The options type is the only thing that
-// differs, so it is the only thing the caller supplies.
-func Serve[O any](stdin io.Reader, stdout io.Writer, d Descriptor, run func(Request, O) (Response, error)) error {
-	in, err := io.ReadAll(stdin)
-	if err != nil {
-		return fmt.Errorf("reading the request: %w", err)
-	}
-
-	var req Request
-	if err := json.Unmarshal(in, &req); err != nil {
-		return fmt.Errorf("the request is not a portolan plugin request: %w", err)
-	}
-	if req.PortolanVersion != "" && req.PortolanVersion != Version {
-		return fmt.Errorf("unsupported portolan protocol %q (plugin supports %s)", req.PortolanVersion, Version)
-	}
-
-	resp := Response{}
-	switch req.Kind {
-	case KindDescribe:
-		// Files is named rather than left nil because the host reads it on
-		// every response, and a describe that answers `"files": null` is a
-		// plugin that looks broken the first time anyone asks it anything.
-		resp = Response{Files: []File{}, Describe: &d}
-	case "":
-		var opts O
-		if len(req.Options) > 0 {
-			if err := json.Unmarshal(req.Options, &opts); err != nil {
-				return fmt.Errorf("options: %w", err)
-			}
-		}
-
-		if resp, err = run(req, opts); err != nil {
-			return err
-		}
-	default:
-		return fmt.Errorf("unknown request kind %q", req.Kind)
-	}
-
-	out, err := json.Marshal(resp)
-	if err != nil {
-		return fmt.Errorf("encoding the response: %w", err)
-	}
-
-	if _, err := stdout.Write(out); err != nil {
-		return fmt.Errorf("writing the response: %w", err)
-	}
-
-	return nil
-}

package/plugin/describe_test.go

@@ -1,114 +0,0 @@
-package plugin_test
-
-import (
-	"bytes"
-	"encoding/json"
-	"strings"
-	"testing"
-
-	"github.com/shortlink-org/portolan/plugin"
-)
-
-type options struct {
-	Context string `json:"context"`
-}
-
-func descriptor() plugin.Descriptor {
-	return plugin.Descriptor{
-		Name:    "example",
-		Phases:  []string{plugin.PhaseExtract},
-		Options: json.RawMessage(`{"type":"object","additionalProperties":false}`),
-	}
-}
-
-func TestServeDescribesWithoutWorking(t *testing.T) {
-	worked := false
-	out := &bytes.Buffer{}
-
-	err := plugin.Serve(strings.NewReader(`{"kind":"describe"}`), out, descriptor(),
-		func(plugin.Request, options) (plugin.Response, error) {
-			worked = true
-
-			return plugin.Response{}, nil
-		})
-	if err != nil {
-		t.Fatalf("describe: %v", err)
-	}
-
-	if worked {
-		t.Error("a describe ran the plugin, which is the one thing it must not do")
-	}
-
-	var resp plugin.Response
-	if err := json.Unmarshal(out.Bytes(), &resp); err != nil {
-		t.Fatalf("the answer is not a response: %v", err)
-	}
-
-	if resp.Describe == nil {
-		t.Fatal("a describe answered without a descriptor")
-	}
-	if resp.Describe.Name != "example" {
-		t.Errorf("descriptor names %q", resp.Describe.Name)
-	}
-
-	// The host reads files on every response, so a describe that answers null
-	// is a plugin that looks broken the first time anyone asks it anything.
-	if !strings.Contains(out.String(), `"files":[]`) {
-		t.Errorf("a describe answered %s, which has no files list", out)
-	}
-}
-
-func TestServeReadsOptions(t *testing.T) {
-	var seen options
-	out := &bytes.Buffer{}
-
-	err := plugin.Serve(
-		strings.NewReader(`{"input":{"root":"examples/auth"},"options":{"context":"auth"}}`),
-		out, descriptor(),
-		func(req plugin.Request, opts options) (plugin.Response, error) {
-			seen = opts
-
-			return plugin.Response{Files: []plugin.File{{Name: req.Input.Root + ".json"}}}, nil
-		})
-	if err != nil {
-		t.Fatalf("run: %v", err)
-	}
-
-	if seen.Context != "auth" {
-		t.Errorf("options came through as %+v", seen)
-	}
-	if !strings.Contains(out.String(), "examples/auth.json") {
-		t.Errorf("the response is %s", out)
-	}
-}
-
-func TestServeRefusesAnUnknownKind(t *testing.T) {
-	err := plugin.Serve(strings.NewReader(`{"kind":"explain"}`), &bytes.Buffer{}, descriptor(),
-		func(plugin.Request, options) (plugin.Response, error) {
-			return plugin.Response{}, nil
-		})
-
-	if err == nil || !strings.Contains(err.Error(), "explain") {
-		t.Errorf("an unknown kind gave %v", err)
-	}
-}
-
-func TestServeRefusesAnIncompatibleProtocol(t *testing.T) {
-	err := plugin.Serve(strings.NewReader(`{"portolanVersion":"9.0.0","kind":"describe"}`), &bytes.Buffer{}, descriptor(),
-		func(plugin.Request, options) (plugin.Response, error) { return plugin.Response{}, nil })
-	if err == nil || !strings.Contains(err.Error(), "unsupported portolan protocol") {
-		t.Errorf("incompatible version gave %v", err)
-	}
-}
-
-func TestWarningsAreNotAResponseProperty(t *testing.T) {
-	b := &plugin.Builder{}
-	b.Warn("fixture", "not represented")
-	out, err := json.Marshal(b.Response())
-	if err != nil {
-		t.Fatal(err)
-	}
-	if strings.Contains(string(out), "diagnostics") || strings.Contains(string(out), "warning") {
-		t.Errorf("warning leaked into wire response: %s", out)
-	}
-}

package/plugin/protocol.go

@@ -1,117 +0,0 @@
-// Package plugin is the wire contract between the host and a generator.
-//
-// One JSON message in, one JSON message out, and the same shape whichever
-// direction the generator runs in: an extractor reads source and answers with
-// a catalog fragment, a renderer reads the catalog and answers with pages.
-// Both name files; neither writes them. The host does that, which is what lets
-// a generator run as a wasm module with nothing preopened at all.
-package plugin
-
-import (
-	"encoding/json"
-	"fmt"
-	"os"
-
-	"github.com/shortlink-org/portolan/catalog"
-)
-
-const Version = "0.1.0"
-
-// Request is everything a plugin is allowed to know. There is no ambient state
-// to read, no environment, and - for a wasm plugin - no filesystem either.
-type Request struct {
-	PortolanVersion string `json:"portolanVersion"`
-
-	// Kind is what the host is asking for. Empty - the only thing anyone sent
-	// before this field existed - means do the work. KindDescribe means answer
-	// with a Descriptor and read nothing: it is how the manifest schema is
-	// built, and it has to be cheap enough to run over every declared plugin.
-	Kind string `json:"kind,omitempty"`
-
-	// Catalog is the merged catalog, for a plugin that renders from it. An
-	// extractor is handed the zero value: it runs before there is one.
-	Catalog catalog.Catalog `json:"catalog"`
-
-	// Input is where a plugin that reads source should look. Empty for a
-	// renderer, which has no business touching the tree.
-	Input Input `json:"input"`
-
-	// Options belong to the plugin and are passed through from the manifest
-	// unread, so the host never has to know what any plugin can be told.
-	Options json.RawMessage `json:"options"`
-}
-
-type Input struct {
-	// Root is the directory to read, relative to the repository.
-	Root string `json:"root"`
-
-	// Output is the directory where the host will place the files returned by
-	// this plugin, relative to the repository. Extractors use it only when a
-	// catalog entry needs to point at a generated companion document.
-	Output string `json:"output,omitempty"`
-
-	// Commit and GeneratedAt stamp the fragment (portolan.0002). The host works them out - the
-	// last commit that touched Root, and its date - rather than the plugin
-	// reading a clock, because a fragment that changes on every run cannot be
-	// committed and cannot be checked. Stamped this way it changes exactly when
-	// the source it describes changes.
-	Commit      string `json:"commit"`
-	GeneratedAt string `json:"generatedAt"`
-}
-
-// Response is what comes back.
-//
-// Files are named, not written (portolan.0001). The host rejects a name that climbs out of the
-// output directory, and that rejection is the whole of a plugin's authority
-// over the tree.
-type Response struct {
-	Files    []File `json:"files"`
-	warnings []Warning
-
-	// Describe answers KindDescribe and is absent otherwise. A plugin written
-	// against an older version of this protocol answers without it, which the
-	// host reports rather than treating as a plugin with no options.
-	Describe *Descriptor `json:"describe,omitempty"`
-}
-
-type File struct {
-	Name     string `json:"name"`
-	Contents string `json:"contents"`
-}
-
-// Warning is an in-process extraction note. It is intentionally not serialized
-// into Response: the wire contract has one decisive outcome, files or error.
-type Warning struct {
-	Severity string `json:"severity"` // "warning" | "error"
-	Message  string `json:"message"`
-	Ref      string `json:"ref,omitempty"`
-}
-
-// Builder accumulates a response. Every plugin needs exactly this and nothing
-// more, so it lives here rather than being written twice.
-type Builder struct {
-	Files    []File
-	Warnings []Warning
-}
-
-func (b *Builder) File(name, contents string) {
-	b.Files = append(b.Files, File{Name: name, Contents: contents})
-}
-
-func (b *Builder) Warn(ref, message string) {
-	b.Warnings = append(b.Warnings, Warning{Severity: "warning", Message: message, Ref: ref})
-	where := ""
-	if ref != "" {
-		where = ref + ": "
-	}
-	fmt.Fprintln(os.Stderr, "warning:", where+message)
-}
-
-func (b *Builder) Response() Response {
-	return Response{Files: b.Files, warnings: b.Warnings}
-}
-
-// Warnings exposes extraction notes to in-process tests and embedders. They
-// are deliberately absent from the JSON protocol: a caller's result is files
-// or an error, not files plus an advisory property nobody is required to act on.
-func (r Response) Warnings() []Warning { return r.warnings }

package/plugin/schematest/schematest.go

@@ -1,126 +0,0 @@
-// Package schematest checks that a plugin's options schema still describes its
-// options struct.
-//
-// The schema is written by hand rather than reflected out of the struct,
-// because what makes it worth having is the prose: which slug a store expects,
-// whose proto package a peer answers for. None of that survives reflection.
-// What reflection is good for is the half nobody would notice going stale - a
-// field renamed, a field added, a schema left behind - so that is all this
-// does.
-package schematest
-
-import (
-	"encoding/json"
-	"reflect"
-	"sort"
-	"strings"
-	"testing"
-)
-
-type document struct {
-	Type                 string                     `json:"type"`
-	AdditionalProperties *bool                      `json:"additionalProperties"`
-	Properties           map[string]json.RawMessage `json:"properties"`
-	Required             []string                   `json:"required"`
-}
-
-// Check reports every way the schema and the struct have come apart.
-//
-// options is a zero value of the plugin's options type; schema is the embedded
-// document it hands back when asked to describe itself.
-func Check(t *testing.T, schema []byte, options any) {
-	t.Helper()
-
-	var doc document
-	if err := json.Unmarshal(schema, &doc); err != nil {
-		t.Fatalf("options schema is not JSON: %v", err)
-	}
-
-	if doc.Type != "object" {
-		t.Errorf("options schema has type %q, want object", doc.Type)
-	}
-
-	// Without this an unknown key validates, and the misspelled option - the
-	// one error this whole mechanism exists to catch - goes through silently.
-	if doc.AdditionalProperties == nil || *doc.AdditionalProperties {
-		t.Error("options schema must set additionalProperties: false")
-	}
-
-	described := keys(doc.Properties)
-	declared := fields(reflect.TypeOf(options))
-
-	for _, name := range missing(declared, described) {
-		t.Errorf("option %q is in the struct but not in the schema", name)
-	}
-	for _, name := range missing(described, declared) {
-		t.Errorf("option %q is in the schema but not in the struct", name)
-	}
-
-	for _, name := range doc.Required {
-		if _, ok := doc.Properties[name]; !ok {
-			t.Errorf("option %q is required but not described", name)
-		}
-	}
-
-	// A property with nothing to say is a property the manifest schema will
-	// offer with no hint of what it means, which is where this started.
-	for name, raw := range doc.Properties {
-		var property struct {
-			Description string `json:"description"`
-		}
-		if err := json.Unmarshal(raw, &property); err != nil {
-			t.Errorf("option %q: %v", name, err)
-
-			continue
-		}
-		if strings.TrimSpace(property.Description) == "" {
-			t.Errorf("option %q has no description", name)
-		}
-	}
-}
-
-// fields are the json names of an options struct, which is the only shape this
-// takes: a plugin's options are a flat object read out of the manifest.
-func fields(t reflect.Type) []string {
-	var names []string
-
-	for i := 0; i < t.NumField(); i++ {
-		tag := t.Field(i).Tag.Get("json")
-		name, _, _ := strings.Cut(tag, ",")
-		if name == "" || name == "-" {
-			continue
-		}
-		names = append(names, name)
-	}
-
-	sort.Strings(names)
-
-	return names
-}
-
-func keys(m map[string]json.RawMessage) []string {
-	names := make([]string, 0, len(m))
-	for name := range m {
-		names = append(names, name)
-	}
-	sort.Strings(names)
-
-	return names
-}
-
-// missing is everything in a that is not in b.
-func missing(a, b []string) []string {
-	have := make(map[string]bool, len(b))
-	for _, name := range b {
-		have[name] = true
-	}
-
-	var gone []string
-	for _, name := range a {
-		if !have[name] {
-			gone = append(gone, name)
-		}
-	}
-
-	return gone
-}

package/plugins/extract-adr/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-adr",
-		Summary: "Reads decision records written by hand - MADR markdown with a title, meta bullets and the record itself, or the numbered records adr-tools writes - into a catalog fragment.",
-		Phases:  []string{plugin.PhaseExtract},
-		Options: optionsSchema,
-	}
-}

package/plugins/extract-adr/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{})
-}