@shortlink-org/portolan 0.1.0

package/plugins/verify-codeowners/owners.go

@@ -0,0 +1,164 @@
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// Where a forge looks for the file, in the order it looks.
+var places = []string{"CODEOWNERS", ".github/CODEOWNERS", "docs/CODEOWNERS"}
+
+// verify reads the file and answers with who owns each service.
+//
+// The catalog it is handed is the merged one, which is the only thing that
+// knows where each service is: a rule is a path, a service has a path, and
+// nothing else in the estate holds both. That is also why this is a verifier
+// rather than an extractor - an extractor is handed a directory and would have
+// to be told, service by service, in the manifest, what the catalog already
+// says.
+func verify(req plugin.Request, opts Options) (plugin.Response, error) {
+	b := &plugin.Builder{}
+
+	at, src, err := read(req.Input.Root, opts.File)
+	if err != nil {
+		return plugin.Response{}, err
+	}
+	rel := filepath.ToSlash(at)
+
+	parsed := parseCodeowners(src)
+	if parsed.Sections {
+		b.Warn(rel, "uses section headers, which change whose rule wins; owners are resolved the way a forge without sections resolves them, so a service may be missing one")
+	}
+	if len(parsed.Rules) == 0 {
+		b.Warn(rel, "states no rules; no service is owned by anybody")
+	}
+
+	// Two different things a rule can fail at, told apart because the fix is
+	// different. A rule that matches nothing names a path the estate does not
+	// have - a typo, or a directory that moved. A rule that matches something
+	// and never wins is alive but unreachable: everything it covers is claimed
+	// further down, and deleting it would change nothing.
+	matched := make([]bool, len(parsed.Rules))
+	won := make([]bool, len(parsed.Rules))
+	contexts := []catalog.BoundedContext{}
+
+	for _, context := range req.Catalog.Contexts {
+		owned := []catalog.Service{}
+
+		for _, service := range context.Services {
+			if service.Path == "" {
+				b.Warn(service.ID, "has no path, so no rule can be matched against it")
+
+				continue
+			}
+
+			// LAST match wins, so the search runs backwards and stops at the
+			// first hit. A rule that matches and names nobody still wins:
+			// taking ownership back is what an empty rule is written for.
+			handles := []string{}
+			first := true
+			for i := len(parsed.Rules) - 1; i >= 0; i-- {
+				if !owns(parsed.Rules[i].Pattern, service.Path) {
+					continue
+				}
+				matched[i] = true
+				if first {
+					first = false
+					won[i] = true
+					handles = append(handles, parsed.Rules[i].Owners...)
+				}
+			}
+			if len(handles) == 0 {
+				b.Warn(service.ID, "is owned by nobody in "+rel)
+
+				continue
+			}
+
+			owned = append(owned, catalog.Service{
+				ID:         service.ID,
+				Slug:       service.Slug,
+				Provides:   []catalog.RpcService{},
+				Consumes:   []catalog.RpcCall{},
+				Aggregates: []catalog.Aggregate{},
+				Owners:     handles,
+			})
+		}
+
+		if len(owned) == 0 {
+			continue
+		}
+		contexts = append(contexts, catalog.BoundedContext{
+			ID:       context.ID,
+			Slug:     context.ID,
+			Services: owned,
+		})
+	}
+
+	// The half of this that is a verification rather than a reading: a rule
+	// nobody matched is a team that believes it owns something it does not,
+	// which is the failure a CODEOWNERS file has and never reports.
+	for i, rule := range parsed.Rules {
+		where := fmt.Sprintf("%s:%d", rel, rule.Line)
+		switch {
+		case !matched[i]:
+			b.Warn(where, rule.Pattern+" matches no service in the catalog")
+		case !won[i]:
+			b.Warn(where, rule.Pattern+" owns no service: everything it matches is claimed by a rule below it")
+		}
+	}
+
+	fragment := catalog.Catalog{
+		GeneratedAt: req.Input.GeneratedAt,
+		Commit:      req.Input.Commit,
+		Contexts:    contexts,
+		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 = "owners.json"
+	}
+	b.File(out, string(encoded)+"\n")
+
+	return b.Response(), nil
+}
+
+// read finds the file and returns where it was and what it says.
+//
+// A named file that is not there fails the run: somebody wrote that path in
+// the manifest, and answering "nobody owns anything" to a typo is the kind of
+// wrong that is only noticed when a page has been missing an owner for a
+// month. Nothing named and nothing found is the same failure said differently,
+// because a step declared at all is a step that expected a file.
+func read(root, named string) (string, string, error) {
+	tried := places
+	if named != "" {
+		tried = []string{named}
+	}
+
+	for _, place := range tried {
+		at := filepath.Join(root, filepath.FromSlash(place))
+		src, err := os.ReadFile(at)
+		if err == nil {
+			return at, string(src), nil
+		}
+		if !os.IsNotExist(err) {
+			return "", "", err
+		}
+	}
+
+	return "", "", fmt.Errorf("no CODEOWNERS under %s: looked for %s",
+		filepath.ToSlash(root), strings.Join(tried, ", "))
+}

package/plugins/verify-codeowners/owners_test.go

@@ -0,0 +1,225 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// An estate of two services in two contexts, which is enough for every rule
+// this has: one owned, one not, one rule that owns nothing.
+func estate() catalog.Catalog {
+	return catalog.Catalog{
+		Contexts: []catalog.BoundedContext{
+			{
+				ID:   "shop",
+				Slug: "shop",
+				Services: []catalog.Service{
+					{ID: "shop.oms", Slug: "oms", Name: "OMS", Path: "examples/shop/oms"},
+					{ID: "shop.cart", Slug: "cart", Name: "Cart", Path: "examples/shop/cart"},
+				},
+			},
+			{
+				ID:   "auth",
+				Slug: "auth",
+				Services: []catalog.Service{
+					{ID: "auth.auth", Slug: "auth", Name: "Auth", Path: "examples/auth"},
+				},
+			},
+		},
+	}
+}
+
+func request(t *testing.T, codeowners string) plugin.Request {
+	t.Helper()
+	root := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(root, ".github"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(root, ".github", "CODEOWNERS"), []byte(codeowners), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	return plugin.Request{
+		Input:   plugin.Input{Root: root, Commit: "abc1234", GeneratedAt: "2026-01-01T00:00:00Z"},
+		Catalog: estate(),
+	}
+}
+
+func fragmentOf(t *testing.T, resp plugin.Response) catalog.Catalog {
+	t.Helper()
+	if len(resp.Files) != 1 {
+		t.Fatalf("files = %d, want one fragment", len(resp.Files))
+	}
+	var parsed catalog.Catalog
+	if err := json.Unmarshal([]byte(resp.Files[0].Contents), &parsed); err != nil {
+		t.Fatalf("fragment is not a catalog: %v", err)
+	}
+
+	return parsed
+}
+
+func ownersOf(c catalog.Catalog, id string) []string {
+	for _, context := range c.Contexts {
+		for _, service := range context.Services {
+			if service.ID == id {
+				return service.Owners
+			}
+		}
+	}
+
+	return nil
+}
+
+// The rule that decides every answer: the file is read top to bottom and the
+// LAST rule that matches wins, which is what lets a broad rule at the top be
+// narrowed underneath.
+func TestTheLastMatchingRuleWins(t *testing.T) {
+	resp, err := verify(request(t, `
+*                  @acme/platform
+examples/shop      @acme/shop-team
+examples/shop/oms  @acme/oms-team
+`), Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	fragment := fragmentOf(t, resp)
+	if got := ownersOf(fragment, "shop.oms"); len(got) != 1 || got[0] != "@acme/oms-team" {
+		t.Errorf("shop.oms owners = %v, want the narrowest rule's", got)
+	}
+	if got := ownersOf(fragment, "shop.cart"); len(got) != 1 || got[0] != "@acme/shop-team" {
+		t.Errorf("shop.cart owners = %v", got)
+	}
+	if got := ownersOf(fragment, "auth.auth"); len(got) != 1 || got[0] != "@acme/platform" {
+		t.Errorf("auth.auth owners = %v, want the catch-all", got)
+	}
+}
+
+// A pattern that matches and names nobody is how a forge takes ownership back.
+// It has to win, or the rule it was written to cancel keeps applying.
+func TestARuleNamingNobodyTakesOwnershipBack(t *testing.T) {
+	resp, err := verify(request(t, "*  @acme/platform\nexamples/shop/oms\n"), Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if got := ownersOf(fragmentOf(t, resp), "shop.oms"); len(got) != 0 {
+		t.Errorf("shop.oms owners = %v, want nobody", got)
+	}
+	if !warned(resp, "shop.oms", "owned by nobody") {
+		t.Errorf("diagnostics = %+v, want the one saying nobody owns it", resp.Warnings())
+	}
+}
+
+// The half that earns the name: a rule matching no service is a team that
+// believes it owns something the estate does not have, which is the failure a
+// CODEOWNERS file has and can never report about itself.
+func TestARuleThatOwnsNothingIsReported(t *testing.T) {
+	resp, err := verify(request(t, "*  @acme/platform\nservices/billing  @acme/billing\n"), Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if !warned(resp, "CODEOWNERS:2", "matches no service") {
+		t.Errorf("diagnostics = %+v, want the one about the unused rule", resp.Warnings())
+	}
+}
+
+// The other way a rule can be dead, and a different fix: it matches, it just
+// never wins, because everything it covers is claimed further down. Saying
+// "matches no service" about a catch-all would be false and would teach a
+// reader to ignore the warning that is true.
+func TestARuleAlwaysOverriddenIsReportedAsSuch(t *testing.T) {
+	resp, err := verify(request(t, "*  @acme/platform\nexamples  @acme/estate\n"), Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if !warned(resp, "CODEOWNERS:1", "claimed by a rule below it") {
+		t.Errorf("diagnostics = %+v, want the one about the overridden catch-all", resp.Warnings())
+	}
+	if warned(resp, "CODEOWNERS:1", "matches no service") {
+		t.Error("the catch-all matches every service; it just never wins")
+	}
+}
+
+func TestSectionsAreReadFlatAndSaidSoOutLoud(t *testing.T) {
+	resp, err := verify(request(t, "[Backend]\n*  @acme/platform\n"), Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	if !warned(resp, "CODEOWNERS", "section headers") {
+		t.Errorf("diagnostics = %+v, want the one about sections", resp.Warnings())
+	}
+	if got := ownersOf(fragmentOf(t, resp), "shop.oms"); len(got) != 1 {
+		t.Errorf("owners = %v; the rules under a section are still read", got)
+	}
+}
+
+// Determinism, the second obligation: the same catalog and the same file
+// produce the same bytes, or `gen:check` reports drift on a run that changed
+// nothing.
+func TestTheFragmentIsStable(t *testing.T) {
+	req := request(t, "*  @acme/platform\nexamples/shop/oms  @acme/oms-team @someone\n")
+
+	first, err := verify(req, Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	second, err := verify(req, Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if first.Files[0].Contents != second.Files[0].Contents {
+		t.Error("two runs wrote different bytes")
+	}
+	// Named in the order the rule names them: a file that lists the team
+	// before the person is showing an order somebody chose.
+	if got := ownersOf(fragmentOf(t, first), "shop.oms"); strings.Join(got, " ") != "@acme/oms-team @someone" {
+		t.Errorf("owners = %v, want the file's order", got)
+	}
+}
+
+// A path in the manifest that is not there is a typo, and answering "nobody
+// owns anything" to a typo is only noticed a month later.
+func TestANamedFileThatIsNotThereFailsTheRun(t *testing.T) {
+	if _, err := verify(request(t, "* @acme/platform\n"), Options{File: "OWNERS"}); err == nil {
+		t.Fatal("a missing file was accepted")
+	}
+}
+
+func TestTheFragmentCarriesTheHostsStamp(t *testing.T) {
+	resp, err := verify(request(t, "* @acme/platform\n"), Options{})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	fragment := fragmentOf(t, resp)
+	if fragment.Commit != "abc1234" || fragment.GeneratedAt != "2026-01-01T00:00:00Z" {
+		t.Errorf("stamp = %q %q", fragment.Commit, fragment.GeneratedAt)
+	}
+	// A context in the fragment is a shell the merge fills in, and its slug
+	// has to equal its id or the validator refuses the union.
+	for _, context := range fragment.Contexts {
+		if context.Slug != context.ID {
+			t.Errorf("context %q has slug %q", context.ID, context.Slug)
+		}
+	}
+}
+
+func warned(resp plugin.Response, ref, contains string) bool {
+	for _, w := range resp.Warnings() {
+		if strings.Contains(w.Ref, ref) && strings.Contains(w.Message, contains) {
+			return true
+		}
+	}
+
+	return false
+}

package/plugins/verify-codeowners/parse.go

@@ -0,0 +1,90 @@
+package main
+
+// The CODEOWNERS grammar, which is smaller than its reputation.
+//
+// A line is a path pattern and the handles that own what it matches. Blank
+// lines and `#` comments are skipped. Later lines win: the file is read top to
+// bottom and the LAST rule that matches a path is the one that owns it, which
+// is what lets a broad rule at the top be narrowed underneath.
+//
+// GitLab adds sections - `[Backend]`, `^[Optional]`, `[Frontend][2]` - and
+// under them the last-match rule applies per section rather than per file. It
+// is read here as the flatter thing GitHub means, and a file that uses them is
+// warned about rather than half-understood in silence, because the difference
+// only ever shows up as an owner quietly missing from a page.
+//
+// Two pieces of gitignore syntax that CODEOWNERS does not have are not
+// implemented, on purpose: `!` negation, which no forge supports here, and
+// character ranges, which they do but nobody writes.
+
+import (
+	"strings"
+)
+
+// Rule is one line: what it matches, who owns it, and where it was written.
+type Rule struct {
+	Pattern string
+	Owners  []string
+	Line    int
+}
+
+// Parsed is a file's rules and what was odd about it.
+type Parsed struct {
+	Rules []Rule
+
+	// Sections is true when the file uses GitLab's section headers, which
+	// change the precedence rule this does not implement.
+	Sections bool
+}
+
+// parseCodeowners reads the file. It does not fail: a line that is not a rule
+// is not a rule, and refusing to describe an estate over a stray word in a
+// file the forge itself skips would be a worse answer than the ownership the
+// rest of the file states.
+func parseCodeowners(src string) Parsed {
+	out := Parsed{Rules: []Rule{}}
+
+	for i, raw := range strings.Split(src, "\n") {
+		line := strings.TrimSpace(stripComment(raw))
+		if line == "" {
+			continue
+		}
+		if isSection(line) {
+			out.Sections = true
+
+			continue
+		}
+
+		fields := strings.Fields(line)
+		// A pattern with no owners is how a forge takes ownership BACK: it
+		// matches, and names nobody. Kept as a rule so that it can win over an
+		// earlier one, which is the only reason anybody writes it.
+		out.Rules = append(out.Rules, Rule{
+			Pattern: fields[0],
+			Owners:  append([]string(nil), fields[1:]...),
+			Line:    i + 1,
+		})
+	}
+
+	return out
+}
+
+// stripComment removes a trailing comment. An escaped `\#` is a literal in a
+// path, and paths with a `#` in them exist, so the escape is honoured.
+func stripComment(line string) string {
+	for i := 0; i < len(line); i++ {
+		if line[i] == '#' && (i == 0 || line[i-1] != '\\') {
+			return line[:i]
+		}
+	}
+
+	return line
+}
+
+// isSection reports a GitLab section header: `[Name]`, optionally required
+// with `^`, optionally with an approval count `[Name][2]`.
+func isSection(line string) bool {
+	line = strings.TrimPrefix(line, "^")
+
+	return strings.HasPrefix(line, "[") && strings.Contains(line, "]")
+}

package/plugins/verify-codeowners/parse_test.go

@@ -0,0 +1,62 @@
+package main
+
+import "testing"
+
+func TestParseReadsRulesAndSkipsTheRest(t *testing.T) {
+	parsed := parseCodeowners(`# Who to ask.
+
+*                       @acme/platform
+/docs                   @acme/writers   @someone
+examples/shop/oms       @acme/oms-team  # the team that wrote it
+
+examples/legacy
+`)
+
+	if parsed.Sections {
+		t.Error("no sections in this file")
+	}
+	if len(parsed.Rules) != 4 {
+		t.Fatalf("rules = %+v, want four", parsed.Rules)
+	}
+	if parsed.Rules[1].Pattern != "/docs" || len(parsed.Rules[1].Owners) != 2 {
+		t.Errorf("second rule = %+v", parsed.Rules[1])
+	}
+	// A trailing comment is not an owner.
+	if got := parsed.Rules[2].Owners; len(got) != 1 || got[0] != "@acme/oms-team" {
+		t.Errorf("third rule owners = %v", got)
+	}
+	// A pattern with nobody after it is how ownership is taken back, so it is
+	// a rule and not a blank line.
+	if parsed.Rules[3].Pattern != "examples/legacy" || len(parsed.Rules[3].Owners) != 0 {
+		t.Errorf("fourth rule = %+v", parsed.Rules[3])
+	}
+	// The line number is what a warning about a rule that owns nothing points at.
+	if parsed.Rules[2].Line != 5 {
+		t.Errorf("line = %d, want 5", parsed.Rules[2].Line)
+	}
+}
+
+func TestParseNoticesSections(t *testing.T) {
+	for _, header := range []string{"[Backend]", "^[Optional]", "[Frontend][2]"} {
+		parsed := parseCodeowners(header + "\n* @acme/platform\n")
+		if !parsed.Sections {
+			t.Errorf("%q was not read as a section header", header)
+		}
+		if len(parsed.Rules) != 1 {
+			t.Errorf("%q: rules = %+v, want the one below it", header, parsed.Rules)
+		}
+	}
+}
+
+// A `#` inside a path is a path, not a comment, when it is escaped - which is
+// the one place the grammar is not "split on the first hash".
+func TestParseKeepsAnEscapedHash(t *testing.T) {
+	parsed := parseCodeowners(`docs/c\#sharp @acme/writers`)
+
+	if len(parsed.Rules) != 1 || parsed.Rules[0].Pattern != `docs/c\#sharp` {
+		t.Fatalf("rules = %+v", parsed.Rules)
+	}
+	if len(parsed.Rules[0].Owners) != 1 {
+		t.Errorf("owners = %v", parsed.Rules[0].Owners)
+	}
+}

package/plugins/verify-otel/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:    "verify-otel",
+		Summary: "Reads OpenTelemetry traces against the catalog and says which hops have been seen running.",
+		Phases:  []string{plugin.PhaseVerify},
+		Options: optionsSchema,
+	}
+}

package/plugins/verify-otel/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/verify-otel/main.go

@@ -0,0 +1,53 @@
+// Command verify-otel reads OpenTelemetry traces and says which hops of the
+// catalog have been seen running.
+//
+// It is a verifier, not an extractor: it runs after the merge, is handed the
+// catalog, and answers with a fragment that mostly re-declares what is already
+// there - the same flows, with `verified` on the steps a trace shows - plus the
+// consumers and calls the traces prove. A sequence no flow describes is written
+// down as observed, so that a reader learns it exists.
+//
+// What a trace can and cannot say is kept strict. A span is a message going one
+// way; it says the hop happened. It does not say a repository method was called,
+// so `call` steps stay declared; and it does not put a service in the catalog,
+// so a call whose far end is not there stays unresolved however often it ran.
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+type Options struct {
+	// Traces are the recordings to read, as globs relative to the input root.
+	// OTLP JSON, one batch per file or one per line.
+	Traces []string `json:"traces"`
+
+	// Services maps a resource's service.name to a catalog service id, for an
+	// estate where the two differ. Without a line here a name is matched to
+	// the one service whose slug it is.
+	Services map[string]string `json:"services,omitempty"`
+
+	// Events maps an event's wire name - the `event.name` attribute,
+	// "auth.PasswordChanged" - to a catalog event id, for an estate where the
+	// event does not declare its wire name and the last segment of the wire
+	// name is not the event's name in the model.
+	Events map[string]string `json:"events,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-verify-otel:", err)
+		os.Exit(1)
+	}
+}
+
+func run(in io.Reader, out io.Writer) error {
+	return plugin.Serve(in, out, descriptor(), verify)
+}