@shortlink-org/portolan 0.2.4 → 0.4.0

package/internal/wsdl/parse_test.go

@@ -0,0 +1,170 @@
+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)
+	}
+}
+
+// A schema copied beside every document that uses it is one finding per
+// namespace, naming the file whose declarations were kept and the files that
+// repeat them. It goes out as a schema warning, not a resolution one, so only
+// the extractor publishing the contracts reports it.
+func TestDuplicateDeclarationsAreSummarisedWithTheirOrigin(t *testing.T) {
+	root := t.TempDir()
+	schema := `
+<schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:common">
+  <complexType name="CodeType"/>
+  <complexType name="AmountType"/>
+  <element name="Ping"/>
+</schema>`
+	writeFixture(t, root, "a/common.xsd", schema)
+	writeFixture(t, root, "b/common.xsd", schema)
+	writeFixture(t, root, "c/common.xsd", schema)
+	writeFixture(t, root, "service.wsdl", `
+<definitions xmlns="http://schemas.xmlsoap.org/wsdl/" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="urn:local">
+  <types>
+    <xs:schema><xs:import namespace="urn:common" schemaLocation="a/common.xsd"/></xs:schema>
+    <xs:schema><xs:import namespace="urn:common" schemaLocation="b/common.xsd"/></xs:schema>
+    <xs:schema><xs:import namespace="urn:common" schemaLocation="c/common.xsd"/></xs:schema>
+  </types>
+  <portType name="Local"><operation name="Ping"/></portType>
+</definitions>`)
+	result, err := Read(root, "service.wsdl")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(result.Warnings) != 0 {
+		t.Errorf("resolution warnings = %v, want none", result.Warnings)
+	}
+	want := "b/common.xsd: duplicate declaration CodeType and 2 more in namespace urn:common (also in c/common.xsd); the declarations in a/common.xsd are used"
+	if len(result.SchemaWarnings) != 1 || result.SchemaWarnings[0] != want {
+		t.Fatalf("schema warnings = %v\nwant [%s]", result.SchemaWarnings, want)
+	}
+}

package/package.json

@@ -2,7 +2,7 @@
   "name": "@shortlink-org/portolan",
   "description": "Generate a navigable architecture catalog from code and specifications.",
   "private": false,
-  "version": "0.2.4",
+  "version": "0.4.0",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/shortlink-org/portolan#readme",
@@ -21,11 +21,23 @@
   },
   "files": [
     "cli",
+    "rules",
     "scripts",
     "src",
     "public",
     "schema",
+    "go.mod",
+    "go.sum",
+    "catalog",
+    "plugin",
+    "internal/gohttp",
+    "internal/gocall",
+    "internal/goscan",
+    "internal/wsdl",
     "plugins/*.wasm",
+    "plugins/cmd/portolan-http-clients",
+    "plugins/extract-http-clients",
+    "plugins/openapi",
     "plugins/*/*.py",
     "plugins/*/*.ts",
     "plugins/*/*.json",
@@ -50,7 +62,7 @@
     "build": "node cli/portolan.mjs build",
     "preview": "vite preview",
     "test": "vitest run",
-    "test:go": "go test ./...",
+    "test:go": "GOFLAGS=-mod=mod go test ./...",
     "pretest:package": "npm run plugins:build",
     "test:package": "node scripts/package-smoke.mjs",
     "test:watch": "vitest",
@@ -58,7 +70,7 @@
     "likec4:gen": "node scripts/gen-likec4.mjs && likec4 gen react likec4 -o src/likec4/generated.jsx --no-use-dot",
     "likec4:validate": "likec4 validate likec4",
     "predev": "npm run likec4:gen",
-    "plugins:build": "GOOS=wasip1 GOARCH=wasm go build -trimpath -ldflags=\"-s -w\" -o plugins/portolan-go.wasm ./plugins/cmd/portolan-go && javac --release 21 -d plugins/extract-java/build plugins/extract-java/src/org/portolan/extract/*.java",
+    "plugins:build": "GOFLAGS=-mod=mod GOOS=wasip1 GOARCH=wasm go build -trimpath -ldflags=\"-s -w\" -o plugins/portolan-go.wasm ./plugins/cmd/portolan-go && javac --release 21 -d plugins/extract-java/build plugins/extract-java/src/org/portolan/extract/*.java && dotnet build plugins/extract-csharp-ddd -c Release --nologo -v q",
     "schema": "npm run plugins:build && node scripts/schema.mjs",
     "schema:check": "npm run plugins:build && node scripts/schema.mjs --check",
     "gen": "npm run plugins:build && node scripts/gen.mjs",
@@ -67,46 +79,47 @@
     "prepack": "npm run plugins:build"
   },
   "dependencies": {
-    "@ai-sdk/openai-compatible": "3.0.45",
-    "@ai-sdk/react": "4.0.98",
+    "@ai-sdk/openai-compatible": "3.0.48",
+    "@ai-sdk/react": "4.0.102",
     "@asyncapi/react-component": "^3.1.8",
     "@clack/prompts": "^1.8.0",
     "@floating-ui/react": "^0.27.20",
     "@headlessui/react": "^2.2.10",
+    "@marcbachmann/cel-js": "^8.0.0",
     "@scalar/api-reference-react": "^0.9.66",
     "@tailwindcss/vite": "^4.0.0",
     "@tanstack/react-query": "^5.102.8",
     "@tanstack/react-table": "^9.2.4",
-    "@tanstack/react-virtual": "^3.14.10",
+    "@tanstack/react-virtual": "^3.14.12",
     "@vitejs/plugin-react": "^6.1.1",
     "@xyflow/react": "^12.11.5",
-    "ai": "7.0.95",
+    "ai": "7.0.99",
     "ajv": "^8.20.0",
     "elkjs": "^0.12.0",
     "html-to-image": "^1.11.13",
     "likec4": "^1.59.2",
     "lowlight": "^3.3.0",
-    "lucide-react": "^1.38.0",
-    "mermaid": "^11.17.2",
+    "lucide-react": "^1.45.0",
+    "mermaid": "^12.0.0",
     "motion": "^13.2.0",
     "oxc-parser": "^0.149.0",
     "oxc-resolver": "^11.24.2",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "react-markdown": "^10.1.0",
     "react-resizable-panels": "^4.12.3",
     "react-router": "^8.3.1",
     "remark-gfm": "^4.0.0",
     "simple-icons": "^16.30.0",
     "tailwindcss": "^4.0.0",
-    "vite": "^8.2.2",
+    "vite": "^8.3.0",
     "vite-plugin-node-polyfills": "^0.28.0",
     "zustand": "^5.0.15"
   },
   "devDependencies": {
-    "@types/node": "^26.5.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
+    "@types/node": "^26.5.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.0"
   }

package/plugin/describe.go

@@ -0,0 +1,156 @@
+// 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"
+)
+
+// Categories a plugin sorts itself under on the plugin index: what it reads,
+// or what it makes. A phase says where in a run a plugin goes; a category
+// says what kind of fact it is after, which is the question a reader choosing
+// extractors for an estate is asking.
+const (
+	// CategoryCode reads a language: the aggregates, events and use cases a
+	// service declares in its source.
+	CategoryCode = "code"
+	// CategoryContracts reads an interface description - OpenAPI, protobuf,
+	// GraphQL, WSDL, AsyncAPI, a registry's schemas.
+	CategoryContracts = "contracts"
+	// CategoryMessaging reads queues, subjects, topics and the jobs on them.
+	CategoryMessaging = "messaging"
+	// CategoryData reads the stores a service keeps and their shape.
+	CategoryData = "data"
+	// CategoryInfrastructure reads what the service is deployed on - the
+	// queues, topics, functions and stores a Terraform module declares, and
+	// the wiring between them that only the infrastructure knows.
+	CategoryInfrastructure = "infrastructure"
+	// CategoryRepository reads what the repository says about itself: its
+	// metadata, its task runners.
+	CategoryRepository = "repository"
+	// CategoryDocuments reads what people wrote by hand: decisions, glossaries,
+	// flows.
+	CategoryDocuments = "documents"
+	// CategoryEvidence checks the catalog against something outside the code:
+	// traces, ownership rules.
+	CategoryEvidence = "evidence"
+	// CategorySources brings in trees from elsewhere for the extractors to read.
+	CategorySources = "sources"
+	// CategoryExports turns the catalog into something else.
+	CategoryExports = "exports"
+)
+
+// 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"`
+
+	// Category is one of the Category constants: what the plugin reads or
+	// makes, which is how the plugin index groups it.
+	Category string `json:"category"`
+
+	// 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"`
+
+	// Needs names what the host must put in the request beyond the tree: a
+	// fact a sandboxed module cannot reach on its own. The one need so far is
+	// NeedHistory (portolan.0007). A host that cannot supply a need leaves
+	// the field out, and the plugin says what it could not do without it.
+	Needs []string `json:"needs,omitempty"`
+}
+
+// NeedHistory asks the host for Input.History: when each file under the root
+// was first committed and last changed, read from git by the host so that the
+// plugin need not run anything.
+const NeedHistory = "history"
+
+// 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

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