@shortlink-org/portolan 0.1.0

package/plugins/extract-flows/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-flows",
+		Summary: "Reads flows written by hand as *.flow.md - one line per hop, frames closed by end - into a catalog fragment.",
+		Phases:  []string{plugin.PhaseExtract},
+		Options: optionsSchema,
+	}
+}

package/plugins/extract-flows/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{})
+}

package/plugins/extract-flows/extract.go

@@ -0,0 +1,91 @@
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// extract reads every flow file the options name and answers with one
+// fragment holding the flows. A file that does not parse fails the whole run,
+// the way a compiler would: a flow written by hand is written to be read, and
+// one silently left out of the catalog is the kind of missing nobody notices.
+func extract(in plugin.Input, opts Options) (plugin.Response, error) {
+	b := &plugin.Builder{}
+
+	patterns := opts.Files
+	if len(patterns) == 0 {
+		patterns = []string{"*.flow.md"}
+	}
+	var files []string
+	seen := map[string]bool{}
+	for _, pattern := range patterns {
+		matches, err := filepath.Glob(filepath.Join(in.Root, pattern))
+		if err != nil {
+			return plugin.Response{}, err
+		}
+		for _, match := range matches {
+			if !seen[match] {
+				seen[match] = true
+				files = append(files, match)
+			}
+		}
+	}
+	sort.Strings(files)
+	if len(files) == 0 {
+		b.Warn(in.Root, "no flow files matched "+strings.Join(patterns, ", ")+"; the fragment holds no flows")
+	}
+
+	flows := []catalog.Flow{}
+	var problems []string
+	slugs := map[string]string{}
+	for _, file := range files {
+		src, err := os.ReadFile(file)
+		if err != nil {
+			return plugin.Response{}, err
+		}
+		rel := filepath.ToSlash(file)
+		flow, errs := parseFlow(rel, string(src))
+		if len(errs) > 0 {
+			problems = append(problems, errs...)
+
+			continue
+		}
+		if other, taken := slugs[flow.Slug]; taken {
+			problems = append(problems, rel+": flow "+flow.Slug+" is already declared in "+other)
+
+			continue
+		}
+		slugs[flow.Slug] = rel
+		flows = append(flows, flow)
+	}
+	if len(problems) > 0 {
+		return plugin.Response{}, errors.New(strings.Join(problems, "\n"))
+	}
+
+	fragment := catalog.Catalog{
+		GeneratedAt: in.GeneratedAt,
+		Commit:      in.Commit,
+		Contexts:    []catalog.BoundedContext{},
+		Defs:        map[string]catalog.TypeDef{},
+		Flows:       flows,
+		Adrs:        []catalog.Adr{},
+	}
+	encoded, err := json.MarshalIndent(fragment, "", "  ")
+	if err != nil {
+		return plugin.Response{}, err
+	}
+	out := opts.Out
+	if out == "" {
+		out = "flows.json"
+	}
+	b.File(out, string(encoded)+"\n")
+
+	return b.Response(), nil
+}

package/plugins/extract-flows/main.go

@@ -0,0 +1,45 @@
+// Command extract-flows reads flows written by hand, in a text form that reads
+// like the sequence diagram it becomes, and answers with a catalog fragment.
+//
+// Some flows will always be written by people: the design doc for something
+// not built yet, the reconstruction after an incident, the path a test does
+// not pin. The catalog's JSON is the wrong place to write them - a tree of
+// nodes, a unique id per step, every lane declared twice - so this is the
+// right one: one file per flow, one line per hop, frames closed by `end`. The
+// format is described in plugins/README.md and held to by parse_test.go.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// Options are what the manifest tells the extractor.
+type Options struct {
+	// Files are the flow files to read, as globs relative to the input root.
+	// Left out, every `*.flow.md` directly under the root.
+	Files []string `json:"files,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-flows:", 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-flows/options.schema.json

@@ -0,0 +1,16 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "files": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "The flow files to read, as globs relative to the input root. Left out, every *.flow.md directly under the root.",
+      "examples": [["*.flow.md"]]
+    },
+    "out": {
+      "type": "string",
+      "description": "Name of the fragment file, inside the step's output directory. Left out, flows.json."
+    }
+  }
+}