@shortlink-org/portolan 0.1.0

package/internal/wsdl/parse_test.go

@@ -0,0 +1,133 @@
+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/package.json

@@ -0,0 +1,117 @@
+{
+  "name": "@shortlink-org/portolan",
+  "description": "Generate a navigable architecture catalog from code and specifications.",
+  "private": false,
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "homepage": "https://github.com/shortlink-org/portolan#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shortlink-org/portolan.git"
+  },
+  "bugs": {
+    "url": "https://github.com/shortlink-org/portolan/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "portolan": "cli/portolan.mjs"
+  },
+  "files": [
+    "cli",
+    "scripts",
+    "src",
+    "public",
+    "schema",
+    "plugins/*.wasm",
+    "plugins/*/*.go",
+    "plugins/*/*.py",
+    "plugins/*/*.ts",
+    "plugins/*/*.json",
+    "plugins/*/*.md",
+    "plugins/*/*.toml",
+    "plugins/*/*.lock",
+    "plugins/*/src",
+    "plugins/extract-java/build",
+    "plugin",
+    "catalog",
+    "internal",
+    "index.html",
+    "vite.config.ts",
+    "tsconfig.json",
+    "portolan.json",
+    "go.mod",
+    "go.sum",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "dev": "node cli/portolan.mjs dev",
+    "build": "node cli/portolan.mjs build",
+    "preview": "vite preview",
+    "test": "vitest run",
+    "test:go": "go test ./...",
+    "pretest:package": "npm run plugins:build",
+    "test:package": "node scripts/package-smoke.mjs",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit && tsc -p plugins/extract-ts",
+    "likec4:gen": "node scripts/gen-likec4.mjs && likec4 gen react likec4 -o src/likec4/generated.jsx",
+    "likec4:validate": "likec4 validate likec4",
+    "predev": "npm run likec4:gen",
+    "plugins:build": "GOOS=wasip1 GOARCH=wasm go build -o plugins/gen-markdown.wasm ./plugins/gen-markdown && GOOS=wasip1 GOARCH=wasm go build -o plugins/gen-mermaid.wasm ./plugins/gen-mermaid && GOOS=wasip1 GOARCH=wasm go build -o plugins/gen-backstage.wasm ./plugins/gen-backstage && javac --release 21 -d plugins/extract-java/build plugins/extract-java/src/org/portolan/extract/*.java",
+    "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",
+    "gen:check": "npm run plugins:build && node scripts/gen.mjs --check",
+    "diff": "node scripts/diff.mjs",
+    "prepack": "npm run plugins:build"
+  },
+  "dependencies": {
+    "@tailwindcss/vite": "^4.0.0",
+    "@vitejs/plugin-react": "^6.1.1",
+    "@ai-sdk/openai-compatible": "3.0.44",
+    "@ai-sdk/react": "4.0.96",
+    "@asyncapi/react-component": "^3.1.8",
+    "@headlessui/react": "^2.2.10",
+    "@scalar/api-reference-react": "^0.9.66",
+    "@tanstack/react-query": "^5.102.8",
+    "@tanstack/react-table": "^9.2.4",
+    "@tanstack/react-virtual": "^3.14.10",
+    "@xyflow/react": "^12.11.5",
+    "ai": "7.0.93",
+    "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",
+    "motion": "^13.2.0",
+    "oxc-parser": "^0.149.0",
+    "oxc-resolver": "^11.24.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.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-plugin-node-polyfills": "^0.28.0",
+    "zustand": "^5.0.15"
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  }
+}

package/plugin/describe.go

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

@@ -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)
+	}
+}

package/plugin/protocol.go

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