@shortlink-org/portolan 0.1.0

package/plugins/extract-river/extract.go

@@ -0,0 +1,507 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"go/ast"
+	"go/token"
+	"path"
+	"sort"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/internal/goscan"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+const riverImport = "github.com/riverqueue/river"
+
+// riverForeign is what River's own names are worth: QueueDefault is the
+// queue called "default", and nothing in the service's tree says so.
+func riverForeign(importPath, name string) (string, bool) {
+	if importPath == riverImport && name == "QueueDefault" {
+		return "default", true
+	}
+	return "", false
+}
+
+type argType struct {
+	key    string
+	name   string
+	kind   string
+	doc    string
+	fields []string
+	at     goscan.Source
+}
+
+type worker struct {
+	key        string
+	name       string
+	args       string
+	entrypoint string
+	at         goscan.Source
+	registered bool
+}
+
+type producer struct {
+	args       string
+	queue      string
+	entrypoint string
+	at         goscan.Source
+}
+
+type queueJob struct {
+	args      *argType
+	worker    *worker
+	producers []producer
+}
+
+// scanner is the tree, and what River leaves in it: the job argument types,
+// the workers over them, and every Insert that names one.
+type scanner struct {
+	*goscan.Tree
+	args       map[string]*argType
+	workers    map[string]*worker
+	registered map[string]bool
+	producers  []producer
+}
+
+func extract(in plugin.Input, opts Options) (plugin.Response, error) {
+	b := &plugin.Builder{}
+	tree, err := goscan.Read(in.Root)
+	if err != nil {
+		return plugin.Response{}, err
+	}
+	tree.Foreign = riverForeign
+	s := &scanner{
+		Tree:       tree,
+		args:       map[string]*argType{},
+		workers:    map[string]*worker{},
+		registered: map[string]bool{},
+	}
+	s.index()
+
+	serviceID := opts.Context + "." + opts.Service
+	channels, flows := s.catalog(serviceID, opts.Context, b)
+	if len(channels) == 0 && len(flows) == 0 {
+		b.Warn(in.Root, "no River jobs joined a JobArgs.Kind declaration to an Insert call or registered Worker")
+	}
+
+	fragment := catalog.Catalog{
+		GeneratedAt: in.GeneratedAt,
+		Commit:      in.Commit,
+		Contexts: []catalog.BoundedContext{{
+			ID:   opts.Context,
+			Slug: opts.Context,
+			Services: []catalog.Service{{
+				ID:         serviceID,
+				Slug:       opts.Service,
+				Provides:   []catalog.RpcService{},
+				Consumes:   []catalog.RpcCall{},
+				Aggregates: []catalog.Aggregate{},
+				Channels:   channels,
+			}},
+		}},
+		Defs:  map[string]catalog.TypeDef{},
+		Flows: flows,
+		Adrs:  []catalog.Adr{},
+	}
+	encoded, err := json.MarshalIndent(fragment, "", "  ")
+	if err != nil {
+		return plugin.Response{}, err
+	}
+	b.File(goscan.FirstNonEmpty(opts.Out, "river.json"), string(encoded)+"\n")
+
+	return b.Response(), nil
+}
+
+func (s *scanner) index() {
+	for _, file := range s.Files {
+		s.indexTypes(file)
+	}
+	for _, file := range s.Files {
+		s.indexKindMethods(file)
+		s.indexWorkers(file)
+		s.indexRegistrations(file)
+	}
+	for key := range s.registered {
+		if found := s.workers[key]; found != nil {
+			found.registered = true
+		}
+	}
+	for _, file := range s.Files {
+		s.indexProducers(file)
+	}
+}
+
+func (s *scanner) indexTypes(file *goscan.File) {
+	for _, decl := range file.Node.Decls {
+		gen, ok := decl.(*ast.GenDecl)
+		if !ok || gen.Tok != token.TYPE {
+			continue
+		}
+		for _, raw := range gen.Specs {
+			spec := raw.(*ast.TypeSpec)
+			body, ok := spec.Type.(*ast.StructType)
+			if !ok {
+				continue
+			}
+			key := file.Pkg + "." + spec.Name.Name
+			doc := ""
+			if spec.Doc != nil {
+				doc = strings.TrimSpace(spec.Doc.Text())
+			} else if gen.Doc != nil {
+				doc = strings.TrimSpace(gen.Doc.Text())
+			}
+			s.args[key] = &argType{key: key, name: spec.Name.Name, doc: doc, fields: s.FieldsOf(body), at: s.At(spec.Pos())}
+		}
+	}
+}
+
+func (s *scanner) indexKindMethods(file *goscan.File) {
+	for _, decl := range file.Node.Decls {
+		fn, ok := decl.(*ast.FuncDecl)
+		if !ok || fn.Recv == nil || fn.Name.Name != "Kind" || fn.Body == nil {
+			continue
+		}
+		key := s.TypeKey(fn.Recv.List[0].Type, file)
+		arg := s.args[key]
+		if arg == nil {
+			continue
+		}
+		ast.Inspect(fn.Body, func(node ast.Node) bool {
+			ret, ok := node.(*ast.ReturnStmt)
+			if !ok || len(ret.Results) != 1 || arg.kind != "" {
+				return true
+			}
+			arg.kind = s.StringOf(ret.Results[0], file, map[string]bool{})
+			return false
+		})
+		if arg.kind != "" {
+			arg.at = s.At(fn.Pos())
+		}
+	}
+}
+
+func (s *scanner) indexWorkers(file *goscan.File) {
+	for _, decl := range file.Node.Decls {
+		fn, ok := decl.(*ast.FuncDecl)
+		if !ok || fn.Recv == nil || fn.Name.Name != "Work" || fn.Type.Params == nil {
+			continue
+		}
+		var args string
+		for _, field := range fn.Type.Params.List {
+			if key := s.riverJobArg(field.Type, file); key != "" {
+				args = key
+				break
+			}
+		}
+		if args == "" {
+			continue
+		}
+		key := s.TypeKey(fn.Recv.List[0].Type, file)
+		s.workers[key] = &worker{
+			key: key, name: goscan.LastSegment(key), args: args,
+			entrypoint: s.riverFunctionKey(file, fn),
+			at:         s.At(fn.Pos()),
+		}
+	}
+}
+
+func (s *scanner) indexRegistrations(file *goscan.File) {
+	ast.Inspect(file.Node, func(node ast.Node) bool {
+		call, ok := node.(*ast.CallExpr)
+		if !ok || len(call.Args) < 2 {
+			return true
+		}
+		sel, ok := call.Fun.(*ast.SelectorExpr)
+		if !ok || (sel.Sel.Name != "AddWorker" && sel.Sel.Name != "AddWorkerSafely") {
+			return true
+		}
+		pkg, ok := sel.X.(*ast.Ident)
+		if !ok || file.Imports[pkg.Name] != riverImport {
+			return true
+		}
+		if key := s.compositeType(call.Args[1], file, nil); key != "" {
+			s.registered[key] = true
+		}
+		return true
+	})
+}
+
+func (s *scanner) indexProducers(file *goscan.File) {
+	usesRiver := false
+	for _, imported := range file.Imports {
+		if imported == riverImport || strings.HasPrefix(imported, riverImport+"/") {
+			usesRiver = true
+		}
+	}
+	if !usesRiver {
+		return
+	}
+	for _, decl := range file.Node.Decls {
+		fn, ok := decl.(*ast.FuncDecl)
+		if !ok || fn.Body == nil {
+			continue
+		}
+		locals := map[string]string{}
+		ast.Inspect(fn.Body, func(node ast.Node) bool {
+			switch item := node.(type) {
+			case *ast.AssignStmt:
+				for i, lhs := range item.Lhs {
+					name, ok := lhs.(*ast.Ident)
+					if !ok || len(item.Rhs) == 0 {
+						continue
+					}
+					rhs := item.Rhs[min(i, len(item.Rhs)-1)]
+					if key := s.compositeType(rhs, file, locals); key != "" {
+						locals[name.Name] = key
+					}
+				}
+			case *ast.DeclStmt:
+				gen, ok := item.Decl.(*ast.GenDecl)
+				if !ok || gen.Tok != token.VAR {
+					break
+				}
+				for _, raw := range gen.Specs {
+					spec := raw.(*ast.ValueSpec)
+					for i, name := range spec.Names {
+						key := s.TypeKey(spec.Type, file)
+						if key == "" && len(spec.Values) > 0 {
+							key = s.compositeType(spec.Values[min(i, len(spec.Values)-1)], file, locals)
+						}
+						if key != "" {
+							locals[name.Name] = key
+						}
+					}
+				}
+			case *ast.CallExpr:
+				sel, ok := item.Fun.(*ast.SelectorExpr)
+				if !ok || (sel.Sel.Name != "Insert" && sel.Sel.Name != "InsertTx") {
+					break
+				}
+				argIndex := 1
+				if sel.Sel.Name == "InsertTx" {
+					argIndex = 2
+				}
+				if len(item.Args) <= argIndex {
+					break
+				}
+				key := s.compositeType(item.Args[argIndex], file, locals)
+				if s.args[key] == nil || s.args[key].kind == "" {
+					break
+				}
+				queue := "default"
+				if len(item.Args) > argIndex+1 {
+					if named := s.queueFrom(item.Args[argIndex+1], file); named != "" {
+						queue = named
+					}
+				}
+				s.producers = append(s.producers, producer{args: key, queue: queue, entrypoint: s.riverFunctionKey(file, fn), at: s.At(item.Pos())})
+			}
+			return true
+		})
+	}
+}
+
+func (s *scanner) catalog(serviceID, owner string, b *plugin.Builder) ([]catalog.Channel, []catalog.Flow) {
+	workerByArgs := map[string]*worker{}
+	for _, found := range s.workers {
+		if found.registered {
+			workerByArgs[found.args] = found
+		}
+	}
+	queues := map[string]map[string]*queueJob{}
+	for _, p := range s.producers {
+		arg := s.args[p.args]
+		if arg == nil || arg.kind == "" {
+			continue
+		}
+		if queues[p.queue] == nil {
+			queues[p.queue] = map[string]*queueJob{}
+		}
+		job := queues[p.queue][p.args]
+		if job == nil {
+			job = &queueJob{args: arg, worker: workerByArgs[p.args]}
+			queues[p.queue][p.args] = job
+		}
+		job.producers = append(job.producers, p)
+	}
+	for args, found := range workerByArgs {
+		seen := false
+		for _, jobs := range queues {
+			if jobs[args] != nil {
+				seen = true
+			}
+		}
+		if !seen {
+			b.Warn(found.at.String(), "registered River worker "+found.name+" handles "+goscan.LastSegment(args)+", but no local Insert call reveals which queue feeds it")
+		}
+	}
+
+	queueNames := make([]string, 0, len(queues))
+	for queue := range queues {
+		queueNames = append(queueNames, queue)
+	}
+	sort.Strings(queueNames)
+	var channels []catalog.Channel
+	var flows []catalog.Flow
+	for _, queue := range queueNames {
+		jobs := queues[queue]
+		keys := make([]string, 0, len(jobs))
+		for key := range jobs {
+			keys = append(keys, key)
+		}
+		sort.Slice(keys, func(i, j int) bool { return jobs[keys[i]].args.kind < jobs[keys[j]].args.kind })
+		channel := catalog.Channel{
+			Address:  queue,
+			Kind:     catalog.ChannelKindJob,
+			Title:    "River work queue",
+			Doc:      "Jobs inserted and handled through github.com/riverqueue/river.",
+			Messages: []catalog.ChannelMessage{},
+		}
+		for _, key := range keys {
+			job := jobs[key]
+			doc := jobDescription(job.args)
+			channel.Messages = append(channel.Messages, catalog.ChannelMessage{Name: job.args.kind, Title: job.args.name, Doc: doc, Direction: catalog.ChannelSend})
+			if channel.Source == "" && len(job.producers) > 0 {
+				channel.Source = job.producers[0].at.String()
+			}
+			if job.worker == nil {
+				b.Warn(job.producers[0].at.String(), "River job "+job.args.kind+" is inserted, but no registered Worker["+job.args.name+"] was found in this component")
+				continue
+			}
+			channel.Messages = append(channel.Messages, catalog.ChannelMessage{Name: job.args.kind, Title: job.worker.name, Doc: "Handled by " + job.worker.name + ".Work. " + doc, Direction: catalog.ChannelReceive})
+			flows = append(flows, riverFlow(serviceID, owner, queue, job))
+		}
+		channels = append(channels, channel)
+	}
+
+	return channels, flows
+}
+
+func riverFlow(serviceID, owner, queue string, job *queueJob) catalog.Flow {
+	broker := "river." + goscan.Slug(queue)
+	slugged := goscan.Slug(goscan.LastSegment(serviceID) + "-river-" + job.args.kind)
+	if queue != "default" {
+		slugged += "-" + goscan.Slug(queue)
+	}
+	doc := jobDescription(job.args)
+	handoff := func(direction string) *catalog.FlowHandoff {
+		return &catalog.FlowHandoff{Kind: "job", Transport: "river", Channel: queue, Message: job.args.kind, Direction: direction}
+	}
+	return catalog.Flow{
+		ID:         "flow." + slugged,
+		Slug:       slugged,
+		Name:       goscan.Title(job.args.kind) + " job",
+		Summary:    "River job `" + job.args.kind + "` is inserted on `" + queue + "` and handled by `" + job.worker.name + ".Work`.",
+		Source:     job.producers[0].at.String(),
+		Trigger:    &catalog.FlowTrigger{Kind: "job", Label: "River · " + queue, Confidence: "high"},
+		EntryPoint: producerEntrypoint(job.producers),
+		Owner:      owner,
+		Participants: []catalog.Participant{
+			{ID: serviceID, Kind: catalog.ParticipantService, Context: stringPtr(owner)},
+			{ID: broker, Kind: catalog.ParticipantBroker, Label: "River · " + queue},
+		},
+		Steps: catalog.FlowNodes{
+			&catalog.Step{Type: "step", ID: "enqueue", From: serviceID, To: broker, Kind: catalog.StepCall, Label: "enqueue " + job.args.kind, Status: catalog.StatusDeclared, Note: doc, Line: job.producers[0].at.String(), Handoff: handoff("send")},
+			&catalog.Step{Type: "step", ID: "work", From: broker, To: serviceID, Kind: catalog.StepCall, Label: job.worker.name + ".Work", Status: catalog.StatusDeclared, Note: "River dispatches `" + job.args.kind + "` to the registered worker.", Line: job.worker.at.String(), ContinuesAt: job.worker.entrypoint, Handoff: handoff("receive")},
+		},
+	}
+}
+
+func producerEntrypoint(producers []producer) string {
+	seen := map[string]bool{}
+	entrypoint := ""
+	for _, producer := range producers {
+		if producer.entrypoint == "" || seen[producer.entrypoint] {
+			continue
+		}
+		seen[producer.entrypoint] = true
+		if entrypoint != "" {
+			return ""
+		}
+		entrypoint = producer.entrypoint
+	}
+	return entrypoint
+}
+
+func (s *scanner) riverFunctionKey(file *goscan.File, fn *ast.FuncDecl) string {
+	name := fn.Name.Name
+	if fn.Recv != nil && len(fn.Recv.List) > 0 {
+		if receiver := s.TypeKey(fn.Recv.List[0].Type, file); receiver != "" {
+			name = goscan.LastSegment(receiver) + "." + name
+		}
+	}
+	return sourceFunctionKey(file, name)
+}
+
+func sourceFunctionKey(file *goscan.File, name string) string {
+	dir := path.Dir(file.Name)
+	if dir == "." || dir == "" {
+		return name
+	}
+	return dir + ":" + name
+}
+
+func (s *scanner) riverJobArg(expr ast.Expr, file *goscan.File) string {
+	expr = goscan.Unwrap(expr)
+	index, ok := expr.(*ast.IndexExpr)
+	if !ok {
+		return ""
+	}
+	sel, ok := index.X.(*ast.SelectorExpr)
+	if !ok || sel.Sel.Name != "Job" {
+		return ""
+	}
+	pkg, ok := sel.X.(*ast.Ident)
+	if !ok || file.Imports[pkg.Name] != riverImport {
+		return ""
+	}
+	return s.TypeKey(index.Index, file)
+}
+
+func (s *scanner) compositeType(expr ast.Expr, file *goscan.File, locals map[string]string) string {
+	expr = goscan.Unwrap(expr)
+	switch value := expr.(type) {
+	case *ast.CompositeLit:
+		return s.TypeKey(value.Type, file)
+	case *ast.Ident:
+		return locals[value.Name]
+	}
+	return ""
+}
+
+func (s *scanner) queueFrom(expr ast.Expr, file *goscan.File) string {
+	expr = goscan.Unwrap(expr)
+	lit, ok := expr.(*ast.CompositeLit)
+	if !ok {
+		return ""
+	}
+	for _, raw := range lit.Elts {
+		field, ok := raw.(*ast.KeyValueExpr)
+		if !ok {
+			continue
+		}
+		name, ok := field.Key.(*ast.Ident)
+		if ok && name.Name == "Queue" {
+			return s.StringOf(field.Value, file, map[string]bool{})
+		}
+	}
+	return ""
+}
+
+func jobDescription(args *argType) string {
+	if len(args.fields) == 0 {
+		return "Arguments: `" + args.name + "`."
+	}
+	fields := args.fields
+	suffix := ""
+	if len(fields) > 10 {
+		suffix = fmt.Sprintf(", and %d more", len(fields)-10)
+		fields = fields[:10]
+	}
+	return "Arguments `" + args.name + "`: `" + strings.Join(fields, "`, `") + "`" + suffix + "."
+}
+
+func stringPtr(value string) *string { return &value }

package/plugins/extract-river/extract_test.go

@@ -0,0 +1,132 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+func write(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 extracted(t *testing.T, root string) (catalog.Catalog, plugin.Response) {
+	t.Helper()
+	resp, err := extract(plugin.Input{Root: root, Commit: "abc", GeneratedAt: "2026-01-01T00:00:00Z"}, Options{Context: "ops", Service: "mailer"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	var out catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &out); err != nil {
+		t.Fatal(err)
+	}
+	return out, resp
+}
+
+func TestExtractsQueuePayloadAndLifecycle(t *testing.T) {
+	root := t.TempDir()
+	write(t, root, "go.mod", "module example.com/mailer\n")
+	write(t, root, "queue/names.go", `package queue
+const Critical = "critical_mail"
+`)
+	write(t, root, "jobs/send.go", `package jobs
+type SendArgs struct {
+  MessageID string `+"`json:\"message_id\"`"+`
+  Attempts int `+"`json:\"attempts,omitempty\"`"+`
+}
+func (SendArgs) Kind() string { return "send_mail" }
+`)
+	write(t, root, "jobs/worker.go", `package jobs
+import (
+  "context"
+  "github.com/riverqueue/river"
+)
+type SendWorker struct { river.WorkerDefaults[SendArgs] }
+func (*SendWorker) Work(context.Context, *river.Job[SendArgs]) error { return nil }
+`)
+	write(t, root, "app/run.go", `package app
+import (
+  "context"
+  "github.com/riverqueue/river"
+  "example.com/mailer/jobs"
+  "example.com/mailer/queue"
+)
+func setup(workers *river.Workers, client interface { Insert(context.Context, river.JobArgs, *river.InsertOpts) (any, error) }, ctx context.Context) {
+  river.AddWorker(workers, &jobs.SendWorker{})
+  args := jobs.SendArgs{MessageID: "1"}
+  _, _ = client.Insert(ctx, args, &river.InsertOpts{Queue: queue.Critical})
+}
+`)
+
+	out, _ := extracted(t, root)
+	service := out.Contexts[0].Services[0]
+	if len(service.Channels) != 1 {
+		t.Fatalf("channels = %+v", service.Channels)
+	}
+	channel := service.Channels[0]
+	if channel.Address != "critical_mail" || channel.Kind != catalog.ChannelKindJob {
+		t.Fatalf("channel = %+v", channel)
+	}
+	if len(channel.Messages) != 2 || channel.Messages[0].Direction != catalog.ChannelSend || channel.Messages[1].Direction != catalog.ChannelReceive {
+		t.Fatalf("messages = %+v", channel.Messages)
+	}
+	if !strings.Contains(channel.Messages[0].Doc, "message_id string") {
+		t.Errorf("payload doc = %q", channel.Messages[0].Doc)
+	}
+	if len(out.Flows) != 1 || len(out.Flows[0].Steps) != 2 {
+		t.Fatalf("flows = %+v", out.Flows)
+	}
+	if out.Flows[0].Steps[0].(*catalog.Step).Label != "enqueue send_mail" || out.Flows[0].Steps[1].(*catalog.Step).Label != "SendWorker.Work" {
+		t.Fatalf("steps = %+v", out.Flows[0].Steps)
+	}
+	if got := out.Flows[0].Steps[1].(*catalog.Step).ContinuesAt; got != "jobs:SendWorker.Work" {
+		t.Fatalf("worker continuation = %q", got)
+	}
+	if got := out.Flows[0].EntryPoint; got != "app:setup" {
+		t.Fatalf("producer entrypoint = %q", got)
+	}
+	enqueue := out.Flows[0].Steps[0].(*catalog.Step).Handoff
+	work := out.Flows[0].Steps[1].(*catalog.Step).Handoff
+	if enqueue == nil || work == nil || enqueue.Direction != "send" || work.Direction != "receive" || enqueue.Transport != "river" || enqueue.Channel != "critical_mail" || enqueue.Message != "send_mail" {
+		t.Fatalf("job handoffs = enqueue %+v, work %+v", enqueue, work)
+	}
+}
+
+func TestProducerWithoutRegisteredWorkerStaysVisible(t *testing.T) {
+	root := t.TempDir()
+	write(t, root, "go.mod", "module example.com/jobs\n")
+	write(t, root, "job.go", `package jobs
+import (
+  "context"
+  "github.com/riverqueue/river"
+)
+type CleanupArgs struct{}
+func (CleanupArgs) Kind() string { return "cleanup" }
+func enqueue(client interface { Insert(context.Context, river.JobArgs, *river.InsertOpts) (any, error) }, ctx context.Context) {
+  _, _ = client.Insert(ctx, CleanupArgs{}, nil)
+}
+`)
+
+	out, resp := extracted(t, root)
+	if got := out.Contexts[0].Services[0].Channels[0].Address; got != "default" {
+		t.Fatalf("queue = %q", got)
+	}
+	if len(out.Flows) != 0 {
+		t.Fatalf("unexpected flows: %+v", out.Flows)
+	}
+	if len(resp.Warnings()) != 1 || !strings.Contains(resp.Warnings()[0].Message, "no registered Worker") {
+		t.Fatalf("warnings = %+v", resp.Warnings())
+	}
+}

package/plugins/extract-river/main.go

@@ -0,0 +1,42 @@
+// Package main is portolan-extract-river: River job declarations, producers
+// and registered workers in a Go repository in, work queues and job flows out.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+
+	"github.com/shortlink-org/portolan/internal/goscan"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+type Options struct {
+	Context string `json:"context"`
+	Service string `json:"service"`
+	Out     string `json:"out,omitempty"`
+}
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-extract-river:", 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")
+		}
+		if opts.Context == "" {
+			opts.Context = goscan.Slug(filepath.Base(req.Input.Root))
+		}
+		if opts.Service == "" {
+			opts.Service = goscan.Slug(filepath.Base(req.Input.Root))
+		}
+
+		return extract(req.Input, opts)
+	})
+}

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

@@ -0,0 +1,21 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "context": {
+      "type": "string",
+      "description": "Slug of the top-level group that owns the component. Defaults to the input directory name.",
+      "examples": ["avia"]
+    },
+    "service": {
+      "type": "string",
+      "description": "Slug of the component that inserts or handles River jobs. Defaults to the input directory name.",
+      "examples": ["billing"]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file inside the step output directory.",
+      "default": "river.json"
+    }
+  }
+}