@shortlink-org/portolan 0.1.0 → 0.2.1

package/plugins/extract-commands/describe.go

@@ -1,19 +0,0 @@
-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-commands",
-		Summary: "Reads the make targets, npm scripts, just recipes and task-runner tasks a repository declares onto its service.",
-		Phases:  []string{plugin.PhaseExtract},
-		Options: optionsSchema,
-	}
-}

package/plugins/extract-commands/describe_test.go

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

package/plugins/extract-commands/extract.go

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

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

@@ -1,55 +0,0 @@
-// 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-csr/avro.go

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

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

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