@shortlink-org/portolan 0.1.0

package/plugins/extract-commands/extract.go

@@ -0,0 +1,79 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"path/filepath"
+	"regexp"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/internal/commands"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+var slug = regexp.MustCompile(`^[a-z][a-z0-9-]*$`)
+
+// extract reads the runner files at the root and answers with a fragment
+// that names the service and lists its commands - and nothing else about
+// it, because everything else is another extractor's to say.
+//
+// A runner file that cannot be read comes back as a warning rather than a
+// failure: a broken Taskfile is a fact about the checkout the page can carry,
+// and the other runners' commands are still worth listing.
+func extract(in plugin.Input, opts Options) (plugin.Response, error) {
+	b := &plugin.Builder{}
+
+	service := opts.Service
+	if service == "" {
+		service = filepath.Base(in.Root)
+	}
+	context := opts.Context
+	if context == "" {
+		context = filepath.Base(filepath.Dir(in.Root))
+	}
+	for _, part := range []string{context, service} {
+		if !slug.MatchString(part) {
+			return plugin.Response{}, errors.New(part + " is not a slug: a service's id is the context and the service, so both have to be one word the way the estate spells them")
+		}
+	}
+
+	cmds, warnings := commands.Read(in.Root)
+	for _, warning := range warnings {
+		b.Warn(in.Root, warning)
+	}
+	if len(cmds) == 0 {
+		b.Warn(in.Root, "no runner file declares a command here - no Makefile, justfile, Taskfile, package.json scripts or pyproject tasks - so the fragment lists none")
+	}
+
+	fragment := catalog.Catalog{
+		GeneratedAt: in.GeneratedAt,
+		Commit:      in.Commit,
+		Contexts: []catalog.BoundedContext{{
+			ID:   context,
+			Slug: context,
+			Services: []catalog.Service{{
+				ID:         context + "." + service,
+				Slug:       service,
+				Provides:   []catalog.RpcService{},
+				Consumes:   []catalog.RpcCall{},
+				Aggregates: []catalog.Aggregate{},
+				Commands:   cmds,
+			}},
+		}},
+		Defs:  map[string]catalog.TypeDef{},
+		Flows: []catalog.Flow{},
+		Adrs:  []catalog.Adr{},
+	}
+
+	encoded, err := json.MarshalIndent(fragment, "", "  ")
+	if err != nil {
+		return plugin.Response{}, err
+	}
+	out := opts.Out
+	if out == "" {
+		out = "commands.json"
+	}
+	b.File(out, string(encoded)+"\n")
+
+	return b.Response(), nil
+}

package/plugins/extract-commands/extract_test.go

@@ -0,0 +1,92 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+func mustWrite(t *testing.T, path, contents string) {
+	t.Helper()
+	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 fragment(t *testing.T, resp plugin.Response) catalog.Catalog {
+	t.Helper()
+	var got catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &got); err != nil {
+		t.Fatal(err)
+	}
+
+	return got
+}
+
+func TestListsCommandsOnTheNamedService(t *testing.T) {
+	root := filepath.Join(t.TempDir(), "shop", "cart")
+	mustWrite(t, filepath.Join(root, "Makefile"), "test: ## Run the tests\n\tgo test ./...\n")
+	mustWrite(t, filepath.Join(root, "package.json"), `{"scripts":{"build":"tsc"}}`)
+
+	resp, err := extract(plugin.Input{Root: root, Commit: "abc", GeneratedAt: "2026-09-07T00:00:00Z"}, Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if resp.Files[0].Name != "commands.json" {
+		t.Errorf("file = %q", resp.Files[0].Name)
+	}
+	got := fragment(t, resp)
+	if got.Commit != "abc" || len(got.Contexts) != 1 || got.Contexts[0].ID != "shop" {
+		t.Fatalf("fragment = %+v", got)
+	}
+	svc := got.Contexts[0].Services[0]
+	if svc.ID != "shop.cart" || svc.Slug != "cart" || svc.Name != "" || svc.Readme != "" {
+		t.Errorf("the fragment claims only the id: %+v", svc)
+	}
+	if len(svc.Commands) != 2 || svc.Commands[0].Run != "make test" || svc.Commands[0].Doc != "Run the tests" || svc.Commands[1].Run != "npm run build" {
+		t.Errorf("commands = %+v", svc.Commands)
+	}
+	if len(resp.Warnings()) != 0 {
+		t.Errorf("warnings = %+v", resp.Warnings())
+	}
+}
+
+func TestOptionsNameTheService(t *testing.T) {
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "justfile"), "dev:\n    cargo run\n")
+
+	resp, err := extract(plugin.Input{Root: root}, Options{Context: "shop", Service: "oms", Out: "cmds.json"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := fragment(t, resp)
+	if resp.Files[0].Name != "cmds.json" || got.Contexts[0].Services[0].ID != "shop.oms" {
+		t.Errorf("file = %q, service = %q", resp.Files[0].Name, got.Contexts[0].Services[0].ID)
+	}
+}
+
+func TestNothingDeclaredWarns(t *testing.T) {
+	resp, err := extract(plugin.Input{Root: t.TempDir()}, Options{Context: "shop", Service: "oms"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(resp.Warnings()) != 1 {
+		t.Errorf("warnings = %+v", resp.Warnings())
+	}
+	if got := fragment(t, resp); len(got.Contexts[0].Services[0].Commands) != 0 {
+		t.Errorf("commands = %+v", got.Contexts[0].Services[0].Commands)
+	}
+}
+
+func TestRefusesANonSlug(t *testing.T) {
+	if _, err := extract(plugin.Input{Root: t.TempDir()}, Options{Context: "Shop Front", Service: "oms"}); err == nil {
+		t.Error("a context with a space in it is not an id")
+	}
+}

package/plugins/extract-commands/main.go

@@ -0,0 +1,55 @@
+// Command extract-commands reads what a developer types against a checkout -
+// the make targets, npm scripts, just recipes and task-runner tasks the
+// repository declares - and answers with a catalog fragment holding them on
+// the service they belong to.
+//
+// It reads the runner files and nothing else. The README that says "run make
+// test" is a claim; the Makefile with a test target is the fact. Fragment
+// merging puts the list on the service the domain extractor described, so
+// this plugin does not need to know anything else about it - only which
+// service it is, which the manifest says.
+//
+// extract-project reads the same files for the component it describes, so a
+// repository read by that plugin does not need this one; this is for the
+// services a domain extractor describes instead.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// Options are what the manifest tells the extractor.
+type Options struct {
+	// Context is the bounded context the service is in. Left out, the name
+	// of the input directory's parent - right for `shop/cart`, and wrong
+	// often enough that the manifest should say.
+	Context string `json:"context,omitempty"`
+
+	// Service is the service the commands belong to, as its slug. Left out,
+	// the name of the input directory.
+	Service string `json:"service,omitempty"`
+
+	// Out names the fragment file.
+	Out string `json:"out,omitempty"`
+}
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-extract-commands:", err)
+		os.Exit(1)
+	}
+}
+
+func run(stdin io.Reader, stdout io.Writer) error {
+	return plugin.Serve(stdin, stdout, descriptor(), func(req plugin.Request, opts Options) (plugin.Response, error) {
+		if req.Input.Root == "" {
+			return plugin.Response{}, fmt.Errorf("no input root: an extractor has nothing to read")
+		}
+
+		return extract(req.Input, opts)
+	})
+}

package/plugins/extract-commands/options.schema.json

@@ -0,0 +1,20 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the bounded context the service is in. Left out, the name of the input directory's parent, which is right for shop/cart and wrong for a repository of its own.",
+      "examples": ["auth", "shop"]
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the service the commands belong to. Left out, the name of the input directory.",
+      "examples": ["cart", "pricing"]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory. Left out, commands.json."
+    }
+  }
+}

package/plugins/extract-csr/avro.go

@@ -0,0 +1,258 @@
+package main
+
+// Avro, read for the two things the catalog keeps: what a record is called and
+// what fields it has.
+//
+// This is deliberately not an Avro implementation. It never resolves a schema
+// against data, never checks compatibility and never validates - a registry
+// has already done all three, and a second opinion here is only a way for the
+// two to disagree. It reads names and shapes, and renders every type as the
+// short label a person reads on a page.
+
+import (
+	"encoding/json"
+	"fmt"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// avro reads one .avsc into the shapes it declares.
+//
+// The first return is the full name of the record at the top, which is the
+// name a message on the bus goes by. The rest are every named record inside
+// it, keyed by full name, because a nested record is a shape shared by
+// whatever else names it and `defs` is where a shared shape lives.
+func avro(raw []byte) (string, map[string]catalog.TypeDef, error) {
+	var node any
+	if err := json.Unmarshal(raw, &node); err != nil {
+		return "", nil, fmt.Errorf("not an Avro schema: %w", err)
+	}
+
+	r := &avroReader{defs: map[string]catalog.TypeDef{}}
+	label, _ := r.typeOf(node, "")
+
+	// A top-level union or array is legal Avro and names no record. The label
+	// is still the honest answer to "what is this called".
+	return label, r.defs, nil
+}
+
+type avroReader struct {
+	defs map[string]catalog.TypeDef
+
+	// open guards a record that names itself inside itself - a comment thread,
+	// a tree - which is ordinary Avro and an infinite recursion here.
+	open map[string]bool
+}
+
+// typeOf renders one Avro type, and returns the defs key when it is a record
+// this reader has written down.
+//
+// enclosing is the namespace inherited from the schema this type sits in,
+// which is how Avro spells a nested name: a record with no namespace of its
+// own belongs to its parent's.
+func (r *avroReader) typeOf(node any, enclosing string) (label, ref string) {
+	switch value := node.(type) {
+	case string:
+		// A bare name is either a primitive or a reference to a shape named
+		// earlier - possibly in another subject entirely, which is what a
+		// registry reference is for. The reference is claimed here and cleared
+		// later if nothing in the estate turns out to declare it, because only
+		// the whole step can say whether the other subject was vendored too.
+		name := qualify(value, enclosing)
+		if primitive(value) {
+			return name, ""
+		}
+
+		return name, name
+
+	case []any:
+		return r.union(value, enclosing), ""
+
+	case map[string]any:
+		return r.object(value, enclosing)
+	}
+
+	return "", ""
+}
+
+// union renders ["null", "string"] as "string?" - the shape a reader wants,
+// rather than the shape the file has.
+func (r *avroReader) union(members []any, enclosing string) string {
+	var (
+		labels   []string
+		nullable bool
+	)
+
+	for _, member := range members {
+		if name, isString := member.(string); isString && name == "null" {
+			nullable = true
+
+			continue
+		}
+		label, _ := r.typeOf(member, enclosing)
+		labels = append(labels, label)
+	}
+
+	switch {
+	case len(labels) == 0:
+		return "null"
+	case nullable:
+		return strings.Join(labels, "|") + "?"
+	}
+
+	return strings.Join(labels, "|")
+}
+
+func (r *avroReader) object(node map[string]any, enclosing string) (label, ref string) {
+	// A logical type is what the field MEANS, and it is what belongs on a
+	// page: "timestamp-millis" says more than the "long" underneath it.
+	if logical, _ := node["logicalType"].(string); logical != "" {
+		return decorate(logical, node), ""
+	}
+
+	kind, _ := node["type"].(string)
+	namespace := firstNonEmpty(text(node["namespace"]), enclosing)
+
+	switch kind {
+	case "record", "error":
+		return r.record(node, namespace)
+
+	case "enum", "fixed":
+		// Named, but not a shape with fields, so there is nothing to put in
+		// defs and the label is the whole answer.
+		return qualify(text(node["name"]), namespace), ""
+
+	case "array":
+		items, _ := r.typeOf(node["items"], namespace)
+
+		return items + "[]", ""
+
+	case "map":
+		values, _ := r.typeOf(node["values"], namespace)
+
+		return "map<string, " + values + ">", ""
+
+	case "":
+		// `{"type": {...}}` with the real type one level down, which is how a
+		// field wraps a schema it wants to annotate.
+		if nested, wrapped := node["type"]; wrapped {
+			return r.typeOf(nested, namespace)
+		}
+
+		return "", ""
+	}
+
+	return kind, ""
+}
+
+func (r *avroReader) record(node map[string]any, namespace string) (label, ref string) {
+	name := qualify(text(node["name"]), namespace)
+	if name == "" {
+		return "", ""
+	}
+
+	if r.open[name] {
+		// Already being read further up the stack: the name is the answer, and
+		// the def it points at is written by the frame that opened it.
+		return name, name
+	}
+	if _, written := r.defs[name]; written {
+		return name, name
+	}
+
+	if r.open == nil {
+		r.open = map[string]bool{}
+	}
+	r.open[name] = true
+	defer delete(r.open, name)
+
+	// The namespace a nested record inherits is this record's, not the one it
+	// was reached from.
+	inner := namespace
+	if own := text(node["namespace"]); own != "" {
+		inner = own
+	} else if at := strings.LastIndex(name, "."); at > 0 {
+		inner = name[:at]
+	}
+
+	fields := []catalog.Field{}
+	for _, entry := range list(node["fields"]) {
+		field, isObject := entry.(map[string]any)
+		if !isObject {
+			continue
+		}
+		fieldName := text(field["name"])
+		if fieldName == "" {
+			continue
+		}
+		fieldLabel, fieldRef := r.typeOf(field["type"], inner)
+		fields = append(fields, catalog.Field{
+			Name: fieldName,
+			Type: fieldLabel,
+			Doc:  text(field["doc"]),
+			Ref:  fieldRef,
+		})
+	}
+
+	r.defs[name] = catalog.TypeDef{Fields: fields}
+
+	return name, name
+}
+
+// decorate spells out the parameters a logical type carries, because
+// "decimal" without them is not a type anybody can act on.
+func decorate(logical string, node map[string]any) string {
+	if logical != "decimal" {
+		return logical
+	}
+
+	precision, hasPrecision := number(node["precision"])
+	if !hasPrecision {
+		return logical
+	}
+	scale, hasScale := number(node["scale"])
+	if !hasScale {
+		scale = 0
+	}
+
+	return fmt.Sprintf("decimal(%d,%d)", precision, scale)
+}
+
+// qualify gives a name its namespace, unless it already carries one or is a
+// primitive - which is the one rule that keeps "string" from becoming
+// "shop.oms.string".
+func qualify(name, namespace string) string {
+	if name == "" || namespace == "" || strings.Contains(name, ".") || primitive(name) {
+		return name
+	}
+
+	return namespace + "." + name
+}
+
+func primitive(name string) bool {
+	switch name {
+	case "null", "boolean", "int", "long", "float", "double", "bytes", "string":
+		return true
+	}
+
+	return false
+}
+
+func text(node any) string {
+	value, _ := node.(string)
+
+	return strings.TrimSpace(value)
+}
+
+func list(node any) []any {
+	values, _ := node.([]any)
+
+	return values
+}
+
+func number(node any) (int, bool) {
+	value, isNumber := node.(float64)
+
+	return int(value), isNumber
+}

package/plugins/extract-csr/describe.go

@@ -0,0 +1,19 @@
+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-csr",
+		Summary: "Reads schemas vendored out of a Confluent Schema Registry and answers with the topics they are registered against and the shapes they declare.",
+		Phases:  []string{plugin.PhaseExtract},
+		Options: optionsSchema,
+	}
+}

package/plugins/extract-csr/describe_test.go

@@ -0,0 +1,11 @@
+package main
+
+import (
+	"testing"
+
+	"github.com/shortlink-org/portolan/plugin/schematest"
+)
+
+func TestOptionsSchemaMatchesStruct(t *testing.T) {
+	schematest.Check(t, optionsSchema, Options{})
+}