@shortlink-org/portolan 0.1.0 → 0.2.0

package/plugins/openapi/ids.go

@@ -1,261 +0,0 @@
-// Package openapi is what two extractors agree on about an OpenAPI document:
-// how its interfaces are named in the catalog, and which operation answers on
-// which route. The server side reads the document to say what a service
-// provides; the client side reads the copy vendored beside a generated client
-// to say what a service calls. Both have to spell `auth.v1.Sessions/login` the
-// same way, or the call would never resolve to the method, and one place is
-// how they do.
-package openapi
-
-import (
-	"fmt"
-	"os"
-	"strings"
-
-	"gopkg.in/yaml.v3"
-)
-
-// APIID is the document's title and major version: `auth` 1.0.0 gives
-// `auth.v1`. It prefixes every interface the document declares.
-func APIID(title, version string) string {
-	name := title
-	if name == "" {
-		name = "api"
-	}
-	name = strings.ReplaceAll(strings.ToLower(name), " ", "-")
-
-	if major, _, ok := strings.Cut(version, "."); ok && major != "" {
-		return name + ".v" + major
-	}
-
-	return name
-}
-
-// DocumentAPIID is the id a document says it goes by in the estate, or the one
-// built from its title and version when it says nothing.
-//
-// `x-portolan-api` in `info` is for a copy vendored from outside the estate:
-// Stripe's document is titled "Stripe API" and versioned "2026-08-26.dahlia",
-// and `stripe-api.v2026-08-26` on every arrow would be the document's words
-// where the estate wants its own. The copy is the consumer's translation
-// boundary already, so it is the one place the estate's name may be written,
-// and both sides of a call read it from there rather than from two manifests.
-func DocumentAPIID(declared, title, version string) string {
-	if declared = strings.TrimSpace(declared); declared != "" {
-		return declared
-	}
-
-	return APIID(title, version)
-}
-
-// ExternalID is the id a system outside the estate goes by when nothing but
-// its own document names it: the document's title as a slug, with a trailing
-// "API" dropped because the system is the thing, not its interface. "Gordian
-// Flights & Ancillaries API" is gordian-flights-ancillaries; "Stripe API" is
-// stripe. Both sides of a call - the extractor that reads the vendored copy
-// for what the system answers on, and the one that reads the client beside it
-// for what this service calls - derive it here, so neither needs the manifest
-// to say it.
-func ExternalID(title string) string {
-	var b strings.Builder
-	dash := false
-	for _, r := range strings.ToLower(strings.TrimSpace(title)) {
-		switch {
-		case r >= 'a' && r <= 'z', r >= '0' && r <= '9':
-			b.WriteRune(r)
-			dash = false
-		case !dash && b.Len() > 0:
-			b.WriteByte('-')
-			dash = true
-		}
-	}
-	id := strings.TrimRight(b.String(), "-")
-	if trimmed := strings.TrimSuffix(id, "-api"); trimmed != "" {
-		id = trimmed
-	}
-
-	return id
-}
-
-// Title is the human form of a tag: users becomes Users, price_list becomes
-// PriceList, because it sits in an id beside a proto-shaped service name.
-func Title(name string) string {
-	var b strings.Builder
-	for _, word := range strings.FieldsFunc(name, func(r rune) bool { return r == '_' || r == '-' || r == ' ' }) {
-		runes := []rune(word)
-		if runes[0] >= 'a' && runes[0] <= 'z' {
-			runes[0] = runes[0] - 'a' + 'A'
-		}
-		b.WriteString(string(runes))
-	}
-
-	return b.String()
-}
-
-// InterfaceID is the contract declared by the OpenAPI document. Tags organise
-// operations inside that contract; they do not create separate interfaces.
-func InterfaceID(api, _ string) string { return api }
-
-// Verbs, in the order the paths object lists them by convention.
-var Verbs = []string{"get", "put", "post", "delete", "options", "head", "patch", "trace"}
-
-// Operation is one route of the document and the name it goes by.
-type Operation struct {
-	// ID is the operationId, or `VERB /path` when the document has none.
-	ID string
-	// Tag is the first tag, retained as document metadata. It does not change
-	// the identity of the contract.
-	Tag string
-	// Verb is upper case: POST.
-	Verb string
-	// Path is the template as written: /v1/users/{userId}.
-	Path string
-}
-
-// Interface is the id of the interface the operation belongs to.
-func (o Operation) Interface(api string) string { return InterfaceID(api, o.Tag) }
-
-// CallID is what a call to this operation is known by in the catalog.
-func (o Operation) CallID(api string) string { return o.Interface(api) + "/" + o.ID }
-
-// Spec is the part of a document these extractors read.
-type Spec struct {
-	API        string
-	Operations []Operation
-
-	// Title, Description and DocsURL are what the document says about the
-	// system it describes, for naming that system when the manifest does not.
-	Title       string
-	Description string
-	DocsURL     string
-}
-
-// Read loads a document and lists its operations. The api id may be
-// overridden by whoever calls, since the manifest may name one.
-func Read(path string) (*Spec, error) {
-	contents, err := os.ReadFile(path)
-	if err != nil {
-		return nil, err
-	}
-	var root yaml.Node
-	if err := yaml.Unmarshal(contents, &root); err != nil {
-		return nil, fmt.Errorf("%s: %w", path, err)
-	}
-	node := &root
-	if node.Kind == yaml.DocumentNode && len(node.Content) > 0 {
-		node = node.Content[0]
-	}
-
-	info := child(node, "info")
-	spec := &Spec{
-		API:         DocumentAPIID(text(child(info, "x-portolan-api")), text(child(info, "title")), text(child(info, "version"))),
-		Title:       text(child(info, "title")),
-		Description: text(child(info, "description")),
-		DocsURL:     text(child(node, "externalDocs", "url")),
-	}
-	for _, p := range entries(child(node, "paths")) {
-		for _, verb := range Verbs {
-			operation := child(p.value, verb)
-			if operation == nil {
-				continue
-			}
-			id := text(child(operation, "operationId"))
-			if id == "" {
-				id = strings.ToUpper(verb) + " " + p.key
-			}
-			tags := list(child(operation, "tags"))
-			tag := ""
-			if len(tags) > 0 {
-				tag = tags[0]
-			}
-			spec.Operations = append(spec.Operations, Operation{ID: id, Tag: tag, Verb: strings.ToUpper(verb), Path: p.key})
-		}
-	}
-
-	return spec, nil
-}
-
-// Find looks up an operation by verb and route. Both sides may spell a path
-// parameter differently - `{userId}` in the document, `%s` in a generated
-// client - so parameters are compared by position, not by name.
-func (s *Spec) Find(verb, path string) (Operation, bool) {
-	want := strings.ToUpper(verb) + " " + shape(path)
-	for _, op := range s.Operations {
-		if op.Verb+" "+shape(op.Path) == want {
-			return op, true
-		}
-	}
-
-	return Operation{}, false
-}
-
-// shape replaces every parameter, however spelled, with one marker.
-func shape(path string) string {
-	var b strings.Builder
-	for _, segment := range strings.Split(strings.TrimSuffix(path, "/"), "/") {
-		if strings.HasPrefix(segment, "{") || segment == "%s" || segment == "%v" || segment == "%d" {
-			b.WriteString("/*")
-
-			continue
-		}
-		b.WriteString("/" + segment)
-	}
-
-	return b.String()
-}
-
-type entry struct {
-	key   string
-	value *yaml.Node
-}
-
-func entries(node *yaml.Node) []entry {
-	if node == nil || node.Kind != yaml.MappingNode {
-		return nil
-	}
-	var out []entry
-	for i := 0; i+1 < len(node.Content); i += 2 {
-		out = append(out, entry{key: node.Content[i].Value, value: node.Content[i+1]})
-	}
-
-	return out
-}
-
-func child(node *yaml.Node, keys ...string) *yaml.Node {
-	for _, key := range keys {
-		if node == nil || node.Kind != yaml.MappingNode {
-			return nil
-		}
-		var next *yaml.Node
-		for i := 0; i+1 < len(node.Content); i += 2 {
-			if node.Content[i].Value == key {
-				next = node.Content[i+1]
-
-				break
-			}
-		}
-		node = next
-	}
-
-	return node
-}
-
-func text(node *yaml.Node) string {
-	if node == nil || node.Kind != yaml.ScalarNode {
-		return ""
-	}
-
-	return strings.TrimSpace(node.Value)
-}
-
-func list(node *yaml.Node) []string {
-	if node == nil || node.Kind != yaml.SequenceNode {
-		return nil
-	}
-	var out []string
-	for _, item := range node.Content {
-		out = append(out, text(item))
-	}
-
-	return out
-}

package/plugins/openapi/ids_test.go

@@ -1,98 +0,0 @@
-package openapi
-
-import (
-	"os"
-	"path/filepath"
-	"testing"
-)
-
-func TestIDs(t *testing.T) {
-	if got := APIID("Auth", "1.2.3"); got != "auth.v1" {
-		t.Errorf("APIID = %q", got)
-	}
-	if got := APIID("", ""); got != "api" {
-		t.Errorf("APIID of nothing = %q", got)
-	}
-	if got := Title("price_list"); got != "PriceList" {
-		t.Errorf("Title = %q", got)
-	}
-	if got := InterfaceID("auth.v1", "sessions"); got != "auth.v1" {
-		t.Errorf("InterfaceID = %q", got)
-	}
-	if got := InterfaceID("auth.v1", ""); got != "auth.v1" {
-		t.Errorf("InterfaceID without a tag = %q", got)
-	}
-	// A vendored copy may say what the estate calls it; a document that says
-	// nothing is named the way it always was.
-	if got := DocumentAPIID(" stripe.v1 ", "Stripe API", "2026-08-26.dahlia"); got != "stripe.v1" {
-		t.Errorf("DocumentAPIID with x-portolan-api = %q", got)
-	}
-	if got := DocumentAPIID("", "Stripe API", "2026-08-26.dahlia"); got != "stripe-api.v2026-08-26" {
-		t.Errorf("DocumentAPIID without = %q", got)
-	}
-}
-
-// A system outside the estate is named by its document's title, and the
-// title's "API" is the interface, not the system.
-func TestExternalID(t *testing.T) {
-	for title, want := range map[string]string{
-		"Gordian Flights & Ancillaries API": "gordian-flights-ancillaries",
-		"Stripe API":                        "stripe",
-		"  Partner   REST API ":             "partner-rest",
-		"API":                               "api",
-		"":                                  "",
-		"Amadeus (Self-Service) v2":         "amadeus-self-service-v2",
-	} {
-		if got := ExternalID(title); got != want {
-			t.Errorf("ExternalID(%q) = %q, want %q", title, got, want)
-		}
-	}
-}
-
-const doc = `openapi: 3.0.3
-info:
-  title: auth
-  version: 1.0.0
-paths:
-  /v1/sessions:
-    post:
-      operationId: login
-      tags: [sessions]
-  /v1/users/{userId}:
-    get:
-      operationId: getUser
-      tags: [users]
-  /v1/health:
-    get: {}
-`
-
-func TestReadAndFind(t *testing.T) {
-	path := filepath.Join(t.TempDir(), "openapi.yaml")
-	if err := os.WriteFile(path, []byte(doc), 0o644); err != nil {
-		t.Fatal(err)
-	}
-	spec, err := Read(path)
-	if err != nil {
-		t.Fatal(err)
-	}
-	if spec.API != "auth.v1" || len(spec.Operations) != 3 {
-		t.Fatalf("spec = %+v", spec)
-	}
-
-	login, ok := spec.Find("post", "/v1/sessions")
-	if !ok || login.CallID(spec.API) != "auth.v1/login" {
-		t.Errorf("login = %+v %v", login, ok)
-	}
-	// A generated client spells the parameter as a format verb.
-	user, ok := spec.Find("GET", "/v1/users/%s")
-	if !ok || user.CallID(spec.API) != "auth.v1/getUser" {
-		t.Errorf("getUser = %+v %v", user, ok)
-	}
-	health, ok := spec.Find("GET", "/v1/health")
-	if !ok || health.CallID(spec.API) != "auth.v1/GET /v1/health" {
-		t.Errorf("an operation without an id or tag = %+v %v", health, ok)
-	}
-	if _, ok := spec.Find("DELETE", "/v1/sessions"); ok {
-		t.Error("a verb the document does not declare was found")
-	}
-}

package/plugins/verify-codeowners/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:    "verify-codeowners",
-		Summary: "Reads the repository's CODEOWNERS against the catalog: who to ask about each service, which services nobody owns, and which rules own nothing.",
-		Phases:  []string{plugin.PhaseVerify},
-		Options: optionsSchema,
-	}
-}

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

@@ -1,75 +0,0 @@
-// Command verify-codeowners says who to ask about each service, by reading the
-// CODEOWNERS file the repository already keeps.
-//
-// Ownership is the question a catalog is opened for and the one it answered
-// worst: `owner` on a flow or a store means the bounded context, not a team,
-// so "who do I ask about shop.oms" had no answer anywhere on the page. The
-// answer was already written down - every repository with review rules has it,
-// in a file the forge itself enforces - and typing it a second time into the
-// manifest would make the copy the thing that goes stale.
-//
-// So it is read, never written, and never resolved. A handle is what the file
-// says and what a reviewer types; turning `@acme/oms-team` into the people in
-// it is a call to a forge's API, which needs a credential this deliberately
-// does not have and would answer differently tomorrow.
-//
-// It is a verifier rather than an extractor because a rule is a path and only
-// the merged catalog knows where each service is. It earns the name twice
-// over: a service no rule matches, and a rule that matches no service, are
-// both reported - the second being the failure a CODEOWNERS file has and can
-// never report about itself, a team believing it owns something it does not.
-//
-// Nothing here is forge-specific. GitHub, GitLab and Gitea read the same file
-// from the same three places; where GitLab's sections change whose rule wins,
-// the file is read the flatter way and said so out loud.
-//
-//	{
-//	  "plugins": [
-//	    { "name": "codeowners", "process": { "command": "go", "args": ["run", "./plugins/verify-codeowners"] } }
-//	  ],
-//	  "verify": [
-//	    { "plugin": "codeowners", "in": ".github", "out": "data", "options": { "out": "owners.json" } }
-//	  ]
-//	}
-//
-// Point `in` at the directory the file is in rather than at the repository
-// root. The host dates a fragment from the last commit to touch the step's
-// input, and the subject of this one is the CODEOWNERS file: rooted at the
-// repository, it would be restamped by every commit ever made.
-package main
-
-import (
-	"fmt"
-	"io"
-	"os"
-
-	"github.com/shortlink-org/portolan/plugin"
-)
-
-// Options are what the manifest tells the verifier.
-type Options struct {
-	// File is the CODEOWNERS to read, relative to the input root. Left out,
-	// the three places a forge looks: CODEOWNERS, .github/CODEOWNERS and
-	// docs/CODEOWNERS, in that order.
-	File string `json:"file,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-codeowners:", 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: there is nowhere to look for a CODEOWNERS")
-		}
-
-		return verify(req, opts)
-	})
-}

package/plugins/verify-codeowners/match.go

@@ -1,85 +0,0 @@
-package main
-
-// Whether a rule owns a directory.
-//
-// CODEOWNERS patterns are gitignore patterns, and the question asked here is
-// narrower than the one gitignore answers: not "does this pattern match this
-// file" but "does this pattern own this SERVICE", where a service is a
-// directory. A rule owns a directory when it matches the directory itself or
-// anything above it - `services/` owns `services/oms` - and does not when it
-// matches only something inside it: `services/oms/internal` is a rule about
-// part of the service, and reading it as ownership of the whole would hand a
-// team a page they never asked for.
-//
-// The two shapes a pattern comes in are the whole of the rule:
-//
-//   - anchored, when it has a `/` anywhere but the end - `services/oms`,
-//     `/docs` - and is matched against the path from the repository root;
-//   - floating, when it is a single segment - `*.go`, `internal` - and matches
-//     that segment at any depth, which is how gitignore has always read one.
-//
-// `*` and `?` stay inside a segment, `**` spans any number of them.
-
-import (
-	"path"
-	"strings"
-)
-
-// owns reports whether pattern owns the directory at target, both written
-// repository-relative and with forward slashes.
-func owns(pattern, target string) bool {
-	pattern = strings.TrimSpace(pattern)
-	target = strings.Trim(target, "/")
-	if pattern == "" || target == "" {
-		return false
-	}
-
-	// A pattern that is only a `/*` or `*` owns everything at that level.
-	anchored := strings.HasPrefix(pattern, "/") || strings.Contains(strings.TrimSuffix(pattern, "/"), "/")
-	pattern = strings.Trim(pattern, "/")
-	if pattern == "" {
-		return true // "/" - the whole repository.
-	}
-
-	segments := strings.Split(target, "/")
-	if !anchored {
-		// Any segment matching means the directory it names is owned, and so
-		// is everything under it - including this one.
-		for _, segment := range segments {
-			if ok, _ := path.Match(pattern, segment); ok {
-				return true
-			}
-		}
-
-		return false
-	}
-
-	return matchPrefix(strings.Split(pattern, "/"), segments)
-}
-
-// matchPrefix reports whether the pattern matches the target or a prefix of
-// it. A pattern longer than the target names something inside the directory
-// and owns no more of it than that.
-func matchPrefix(pattern, target []string) bool {
-	if len(pattern) == 0 {
-		return true // Every segment of the pattern matched; the rest is inside it.
-	}
-	if pattern[0] == "**" {
-		// Zero or more segments: try here, then one deeper.
-		for i := 0; i <= len(target); i++ {
-			if matchPrefix(pattern[1:], target[i:]) {
-				return true
-			}
-		}
-
-		return false
-	}
-	if len(target) == 0 {
-		return false
-	}
-	if ok, _ := path.Match(pattern[0], target[0]); !ok {
-		return false
-	}
-
-	return matchPrefix(pattern[1:], target[1:])
-}

package/plugins/verify-codeowners/match_test.go

@@ -1,47 +0,0 @@
-package main
-
-import "testing"
-
-// The rule the whole plugin turns on: a pattern owns a directory when it names
-// the directory or anything above it, and does not when it names only
-// something inside it.
-func TestOwns(t *testing.T) {
-	cases := []struct {
-		pattern string
-		target  string
-		want    bool
-		why     string
-	}{
-		{"examples/shop/oms", "examples/shop/oms", true, "the directory itself"},
-		{"examples/shop", "examples/shop/oms", true, "a directory above it"},
-		{"examples/", "examples/shop/oms", true, "a trailing slash is still a directory"},
-		{"/examples", "examples/shop/oms", true, "anchored at the root"},
-		{"*", "examples/shop/oms", true, "everything"},
-		{"/", "examples/shop/oms", true, "the whole repository"},
-
-		{"examples/shop/oms/internal", "examples/shop/oms", false, "a rule about part of the service is not a rule about the service"},
-		{"examples/auth", "examples/shop/oms", false, "a sibling"},
-		{"docs", "examples/shop/oms", false, "somewhere else entirely"},
-
-		// Floating patterns match at any depth, which is what gitignore has
-		// always meant by a pattern with no slash in it.
-		{"oms", "examples/shop/oms", true, "a single segment matches at any depth"},
-		{"shop", "examples/shop/oms", true, "including a segment above"},
-		{"om", "examples/shop/oms", false, "and matches whole segments, not prefixes"},
-
-		{"examples/*/oms", "examples/shop/oms", true, "a star stays inside its segment"},
-		{"examples/*", "examples/shop/oms", true, "and matches the segment above"},
-		{"examples/*/oms", "examples/shop/cart/oms", false, "so it does not cross a slash"},
-		{"examples/**/oms", "examples/shop/cart/oms", true, "two stars do"},
-		{"examples/**", "examples/shop/oms", true, "two stars also match nothing at all"},
-
-		{"", "examples/shop/oms", false, "an empty pattern owns nothing"},
-		{"examples", "", false, "and nothing is owned by no pattern"},
-	}
-
-	for _, c := range cases {
-		if got := owns(c.pattern, c.target); got != c.want {
-			t.Errorf("owns(%q, %q) = %v, want %v - %s", c.pattern, c.target, got, c.want, c.why)
-		}
-	}
-}