@shortlink-org/portolan 0.2.4 → 0.4.0

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 }

package/plugin/schematest/schematest.go

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