@shortlink-org/portolan 0.1.0

package/plugins/extract-project/extract_test.go

@@ -0,0 +1,109 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+func TestExtractsANeutralApplicationWithoutDDD(t *testing.T) {
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "README.md"), "# Flight support\n\nCoordinates providers.\n")
+	mustWrite(t, filepath.Join(root, "go.mod"), "module example.com/flight/support\n")
+	mustWrite(t, filepath.Join(root, "cmd", "support", "main.go"), "package main\n")
+	mustWrite(t, filepath.Join(root, "Dockerfile"), "FROM scratch\n")
+	mustWrite(t, filepath.Join(root, "Makefile"), "build: ## Compile the binary\n\tgo build ./cmd/support\n")
+
+	response, err := extract(plugin.Input{Root: root, Commit: "abc", GeneratedAt: "2026-09-06T00:00:00Z"}, Options{Group: "avia", Component: "support"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got catalog.Catalog
+	if err := json.Unmarshal([]byte(response.Files[0].Contents), &got); err != nil {
+		t.Fatal(err)
+	}
+	group := got.Contexts[0]
+	component := group.Services[0]
+	if group.Kind != catalog.GroupKindSystem {
+		t.Errorf("group kind = %q", group.Kind)
+	}
+	if component.Kind != catalog.ComponentKindApplication {
+		t.Errorf("component kind = %q", component.Kind)
+	}
+	if component.Name != "Flight support" || component.Repo != "example.com/flight/support" {
+		t.Errorf("component = %+v", component)
+	}
+	if len(component.Technologies) != 2 || component.Technologies[0] != "Go" || component.Technologies[1] != "Docker" {
+		t.Errorf("technologies = %v", component.Technologies)
+	}
+	if len(component.Aggregates) != 0 {
+		t.Fatalf("invented aggregates: %+v", component.Aggregates)
+	}
+	if len(component.Commands) != 1 || component.Commands[0].Run != "make build" || component.Commands[0].Doc != "Compile the binary" {
+		t.Errorf("commands = %+v", component.Commands)
+	}
+}
+
+func TestExplicitKindsWin(t *testing.T) {
+	root := t.TempDir()
+	response, err := extract(plugin.Input{Root: root}, Options{Group: "platform", GroupKind: "team", Component: "tools", ComponentKind: "cli"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var got catalog.Catalog
+	if err := json.Unmarshal([]byte(response.Files[0].Contents), &got); err != nil {
+		t.Fatal(err)
+	}
+	if got.Contexts[0].Kind != catalog.GroupKindTeam || got.Contexts[0].Services[0].Kind != catalog.ComponentKindCLI {
+		t.Fatalf("explicit kinds were lost: %+v", got.Contexts[0])
+	}
+}
+
+func TestMarkdownTitleIgnoresShellCommentsInsideFences(t *testing.T) {
+	md := "## Getting started\n\n```sh\nmake migrate\n# add superuser\n```\n\n# Actual service\n"
+	if got := markdownTitle(md); got != "Actual service" {
+		t.Fatalf("markdownTitle = %q", got)
+	}
+	md = "~~~sh\n# also not a title\n~~~\n"
+	if got := markdownTitle(md); got != "" {
+		t.Fatalf("markdownTitle without a real H1 = %q", got)
+	}
+}
+
+func TestRecognizesMessagingLibrariesAsTechnologies(t *testing.T) {
+	root := t.TempDir()
+	mustWrite(t, filepath.Join(root, "go.mod"), `module example.com/worker
+require (
+	github.com/riverqueue/river v0.26.0
+	github.com/ThreeDotsLabs/watermill v1.5.1
+	github.com/ThreeDotsLabs/watermill-kafka/v2 v2.5.0
+)
+`)
+
+	got := technologies(root)
+	for _, want := range []string{"Kafka", "River", "Watermill"} {
+		found := false
+		for _, value := range got {
+			if value == want {
+				found = true
+			}
+		}
+		if !found {
+			t.Errorf("technologies %v do not contain %q", got, want)
+		}
+	}
+}
+
+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)
+	}
+}

package/plugins/extract-project/main.go

@@ -0,0 +1,41 @@
+// Package main is portolan-extract-project: a repository component in, a
+// neutral catalog fragment out. It deliberately makes no DDD assumptions.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+type Options struct {
+	Group        string `json:"group,omitempty"`
+	GroupName    string `json:"groupName,omitempty"`
+	GroupSummary string `json:"groupSummary,omitempty"`
+	GroupKind    string `json:"groupKind,omitempty"`
+
+	Component     string   `json:"component,omitempty"`
+	ComponentName string   `json:"componentName,omitempty"`
+	ComponentKind string   `json:"componentKind,omitempty"`
+	Technologies  []string `json:"technologies,omitempty"`
+	Repo          string   `json:"repo,omitempty"`
+	Out           string   `json:"out,omitempty"`
+}
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-extract-project:", 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-project/options.schema.json

@@ -0,0 +1,48 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "group": {
+      "type": "string",
+      "description": "Slug of the neutral top-level group. Defaults to the input directory name."
+    },
+    "groupName": {
+      "type": "string",
+      "description": "Human-readable group name. Defaults to the group slug, titled."
+    },
+    "groupSummary": {
+      "type": "string",
+      "description": "A short statement of what the group is responsible for."
+    },
+    "groupKind": {
+      "enum": ["bounded-context", "system", "product", "team", "namespace"],
+      "description": "Semantic role of the top-level group. Defaults to system for this neutral extractor."
+    },
+    "component": {
+      "type": "string",
+      "description": "Slug of the component. Defaults to the input directory name."
+    },
+    "componentName": {
+      "type": "string",
+      "description": "Human-readable component name. Defaults to the README title and then the slug, titled."
+    },
+    "componentKind": {
+      "enum": ["service", "application", "webapp", "worker", "job", "function", "cli", "library", "data-pipeline"],
+      "description": "Runtime or code role. When absent, the extractor uses conservative repository evidence."
+    },
+    "technologies": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "Languages and frameworks, stated when the tree cannot say: a component whose manifests sit above its root, one of several in a repository, has nothing at its root to read. Left out, inferred from go.mod, package.json, Cargo.toml and the like at the root."
+    },
+    "repo": {
+      "type": "string",
+      "description": "Source repository identity. Defaults to a Go module, package.json repository, Cargo package, or Maven coordinates when present."
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file inside the step output directory.",
+      "default": "project.json"
+    }
+  }
+}

package/plugins/extract-proto/ast.go

@@ -0,0 +1,125 @@
+package main
+
+// What a .proto file says, as it says it.
+//
+// Types are kept AS WRITTEN - `repeated Money`, `map<string, LineItem>`, the
+// `optional` keyword, the author's declaration order. The catalog already
+// takes this stance for schemas ("the db type as declared - uuid, timestamptz,
+// jsonb - never normalised"), and a reader comparing a page against the file it
+// came from should recognise what they are looking at.
+
+// File is one parsed .proto.
+type File struct {
+	// Path is the file as a reader would type it, relative to the repo root.
+	Path string
+
+	// Doc is the comment at the very top of the file, above `syntax`.
+	//
+	// On a vendored copy this is where the header lives that says which module
+	// it came from - docs/adr/org.0001.md requires one - so it is worth keeping
+	// apart from the documentation of any declaration inside.
+	Doc string
+
+	Syntax   string // "proto2", "proto3", "editions", or "" when unstated
+	Package  string
+	Imports  []Import
+	Options  []Option
+	Messages []*Message
+	Enums    []*Enum
+	Services []*Service
+}
+
+type Import struct {
+	Path   string
+	Public bool
+	Weak   bool
+	Line   int
+}
+
+type Option struct {
+	Name  string
+	Value string
+	Line  int
+}
+
+type Message struct {
+	Name string
+	Doc  string
+	Line int
+
+	// Fields holds every field of the message, including the members of its
+	// oneofs, in declaration order. A oneof is a constraint on which of them may
+	// be set, not a separate place a field lives, so a reader asking "what is in
+	// this message" gets one list.
+	Fields   []*Field
+	Oneofs   []*Oneof
+	Messages []*Message // nested
+	Enums    []*Enum
+	Reserved []string
+}
+
+type Field struct {
+	Name string
+	Doc  string
+	Line int
+
+	// Type as written: "string", "Money", "shop.v1.Money", "map<string, Money>".
+	Type   string
+	Label  string // "", "repeated", "optional", "required"
+	Number int
+
+	// Oneof names the oneof this field belongs to, empty when it is not in one.
+	Oneof      string
+	Deprecated bool
+	Default    string
+}
+
+type Oneof struct {
+	Name   string
+	Doc    string
+	Line   int
+	Fields []*Field
+}
+
+type Enum struct {
+	Name   string
+	Doc    string
+	Line   int
+	Values []*EnumValue
+}
+
+type EnumValue struct {
+	Name   string
+	Doc    string
+	Number int
+	Line   int
+}
+
+type Service struct {
+	Name    string
+	Doc     string
+	Line    int
+	Methods []*Method
+}
+
+type Method struct {
+	Name string
+	Doc  string
+	Line int
+
+	Request         string
+	Response        string
+	ClientStreaming bool
+	ServerStreaming bool
+	Deprecated      bool
+}
+
+// Note is something the parser declined to model, named rather than dropped.
+//
+// A construct the parser skips silently is a construct nobody knows is missing.
+// Every one of these becomes a plugin diagnostic, so an estate using `extend`
+// or a proto2 `group` finds out that portolan read past it.
+type Note struct {
+	Line    int
+	Message string
+}

package/plugins/extract-proto/consumes.go

@@ -0,0 +1,77 @@
+package main
+
+// What a service CALLS, read from the client copies it vendors.
+//
+// docs/adr/org.0001.md puts a narrowed copy of the producer's proto in the
+// consumer's infrastructure layer, with a header comment saying where it came
+// from. That copy is a statement about what this service intends to call, and
+// reading it is how a call edge gets into the catalog from the calling end.
+
+import (
+	"sort"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// calls turns every method in the vendored files into a catalog call.
+//
+// STATUS IS ALWAYS "declared", NEVER "verified". Three reasons, and the test
+// that holds this is deliberate:
+//
+//  1. `problems()` treats status as authored, not derived.
+//  2. Verification is a property of the UNION, and every extractor runs before
+//     one exists - `plugin.Request.Catalog` is the zero value for an extractor.
+//  3. In the shipped catalog `verified` already means something a proto cannot
+//     supply: it sits next to a note naming the integration test that covers
+//     the call end to end.
+//
+// Reading a .proto proves the call was WRITTEN DOWN, which is what `declared`
+// means. Whether it is exercised is not a question this file can answer.
+func calls(files []*File, peers map[string]string, moduleID string, b *plugin.Builder) []catalog.RpcCall {
+	var out []catalog.RpcCall
+
+	for _, file := range files {
+		peer, named := peers[file.Package]
+		if !named {
+			// The raw package name, which is exactly what `RpcCall.peer`
+			// documents: "service id if resolved, else raw name". Guessing a
+			// service id from a proto package would be inventing an edge.
+			peer = file.Package
+		}
+
+		for _, svc := range file.Services {
+			iface := interfaceID(file.Package, svc.Name)
+			if !named {
+				b.Warn(iface, "no peer is mapped for proto package "+file.Package+
+					"; the call is listed against the package name")
+			}
+
+			for _, m := range svc.Methods {
+				out = append(out, catalog.RpcCall{
+					ID:     callID(iface, m.Name),
+					Peer:   peer,
+					Status: catalog.StatusDeclared,
+					Source: sourceRef(file.Path, m.Line),
+					Note:   file.headerNote(),
+					Module: moduleID,
+				})
+			}
+		}
+	}
+
+	sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID })
+
+	return out
+}
+
+// headerNote is the comment at the top of a vendored copy.
+//
+// The ADR already requires that header - "the header comment on every vendored
+// copy says so" - so surfacing it costs nothing and makes the boundary
+// self-documenting on the page rather than only in the file. It sits above
+// `syntax` rather than above a declaration, which is why the parser keeps it
+// on the file instead of on whatever happens to come first.
+func (f *File) headerNote() string {
+	return f.Doc
+}

package/plugins/extract-proto/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-proto",
+		Summary: "Reads .proto files and answers with what a service provides from the modules it publishes and what it calls from the copies it vendors.",
+		Phases:  []string{plugin.PhaseExtract},
+		Options: optionsSchema,
+	}
+}