@shortlink-org/portolan 0.2.4 → 0.3.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.3.0",
   "type": "module",
   "license": "MIT",
   "homepage": "https://github.com/shortlink-org/portolan#readme",
@@ -25,7 +25,18 @@
     "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",
@@ -67,12 +78,13 @@
     "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.47",
+    "@ai-sdk/react": "4.0.100",
     "@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",
@@ -80,19 +92,19 @@
     "@tanstack/react-virtual": "^3.14.10",
     "@vitejs/plugin-react": "^6.1.1",
     "@xyflow/react": "^12.11.5",
-    "ai": "7.0.95",
+    "ai": "7.0.97",
     "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",
+    "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",
@@ -104,9 +116,9 @@
     "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,118 @@
+// 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"`
+
+	// 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)
+	}
+}

package/plugin/protocol.go

@@ -0,0 +1,141 @@
+// 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"`
+
+	// Provenance is not part of the request (portolan.0010). A fragment used
+	// to carry a commit and a date that the host worked out from the last
+	// commit touching Root and every plugin copied to the top of its output.
+	// The host now reads both from the git history of the fragment it wrote,
+	// so a plugin has nothing to stamp and no clock to read: its output
+	// changes exactly when the source it describes changes, and when that was
+	// is a fact about the file, not a field in it.
+
+	// History is when each file under Root was first committed and last
+	// changed, keyed by the file's path as the plugin would name it - the same
+	// relative form as Root. Present only for a plugin whose descriptor asks
+	// (NeedHistory) and only when Root lies inside a git checkout; a plugin
+	// that asked and finds nil knows there was no history to read. The host
+	// reads it (portolan.0007) so that no plugin has to run git, which a wasm
+	// module cannot.
+	History map[string]FileHistory `json:"history,omitempty"`
+}
+
+// FileHistory is one file's first and last commit. Revised is nil when the
+// file has one commit.
+type FileHistory struct {
+	Created Commit  `json:"created"`
+	Revised *Commit `json:"revised,omitempty"`
+}
+
+// Commit is one commit as the host read it: full sha, author name, and the
+// committer date in strict ISO 8601.
+type Commit struct {
+	Commit string `json:"commit"`
+	Author string `json:"author"`
+	Date   string `json:"date"`
+}
+
+// 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 }