@shortlink-org/portolan 0.1.0

package/plugins/openapi/ids_test.go

@@ -0,0 +1,98 @@
+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/pyplugin/catalog.py

@@ -0,0 +1,209 @@
+"""The shapes of a fragment, in the order `catalog/model.go` declares them.
+
+A mirror, not a second definition: `src/catalog.ts` is where the shape is
+decided. Building the JSON here rather than at each call site is what keeps the
+key order - and so the diff of a regenerated fragment - stable.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+DECLARED = "declared"
+UNRESOLVED = "unresolved"
+
+
+def field(name: str, type_: str, doc: str = "", ref: str = "") -> Dict[str, Any]:
+    out = {"name": name, "type": type_, "doc": doc}
+    if ref:
+        out["ref"] = ref
+    return out
+
+
+def block(id_: str, slug: str, name: str, doc: str, fields: List[Dict[str, Any]]) -> Dict[str, Any]:
+    return {"id": id_, "slug": slug, "name": name, "doc": doc, "fields": fields}
+
+
+def event(id_: str, slug: str, name: str, versions: List[Dict[str, Any]], wire: Optional[Dict[str, str]]) -> Dict[str, Any]:
+    out: Dict[str, Any] = {"id": id_, "slug": slug, "name": name, "versions": versions, "consumers": []}
+    if wire:
+        out["wire"] = wire
+    return out
+
+
+def version(doc: str, source: str, fields: List[Dict[str, Any]], name: str = "v1") -> Dict[str, Any]:
+    return {"version": name, "doc": doc, "source": source, "fields": fields}
+
+
+def operation(id_: str, kind: str, doc: str = "", exposed_by: Optional[List[str]] = None) -> Dict[str, Any]:
+    out: Dict[str, Any] = {"id": id_, "kind": kind}
+    if doc:
+        out["doc"] = doc
+    if exposed_by:
+        out["exposedBy"] = sorted(exposed_by)
+    return out
+
+
+def aggregate(id_: str, slug: str, name: str, readme: str, root: str) -> Dict[str, Any]:
+    return {
+        "id": id_,
+        "slug": slug,
+        "name": name,
+        "readme": readme,
+        "root": root,
+        "entities": [],
+        "valueObjects": [],
+        "operations": [],
+        "events": [],
+    }
+
+
+def transition(from_: str, to: str, on: str, emits: str, source: str) -> Dict[str, Any]:
+    out = {"from": from_, "to": to, "on": on}
+    if emits:
+        out["emits"] = emits
+    if source:
+        out["source"] = source
+    return out
+
+
+def channel(address: str, kind: str, title: str, doc: str, messages: List[Dict[str, Any]], source: str = "") -> Dict[str, Any]:
+    out: Dict[str, Any] = {"address": address}
+    if kind:
+        out["kind"] = kind
+    if title:
+        out["title"] = title
+    if doc:
+        out["doc"] = doc
+    out["messages"] = messages
+    if source:
+        out["source"] = source
+    return out
+
+
+def message(name: str, title: str, doc: str, direction: str) -> Dict[str, Any]:
+    out: Dict[str, Any] = {"name": name}
+    if title:
+        out["title"] = title
+    if doc:
+        out["doc"] = doc
+    out["direction"] = direction
+    return out
+
+
+def rpc_call(id_: str, peer: str, status: str, source: str, note: str = "") -> Dict[str, Any]:
+    out = {"id": id_, "peer": peer, "status": status, "source": source}
+    if note:
+        out["note"] = note
+    return out
+
+
+def participant(id_: str, kind: str, context: Optional[str], label: str = "") -> Dict[str, Any]:
+    out: Dict[str, Any] = {"id": id_, "kind": kind, "context": context}
+    if label:
+        out["label"] = label
+    return out
+
+
+def step(
+    id_: str,
+    from_: str,
+    to: str,
+    kind: str,
+    label: str,
+    status: str,
+    ref: str = "",
+    note: str = "",
+    line: str = "",
+    continues_at: str = "",
+    handoff: Optional[Dict[str, str]] = None,
+) -> Dict[str, Any]:
+    out: Dict[str, Any] = {"type": "step", "id": id_, "from": from_, "to": to, "kind": kind}
+    if label:
+        out["label"] = label
+    out["status"] = status
+    if ref:
+        out["ref"] = ref
+    if note:
+        out["note"] = note
+    if line:
+        out["line"] = line
+    if continues_at:
+        out["continuesAt"] = continues_at
+    if handoff:
+        out["handoff"] = handoff
+    return out
+
+
+def alt(id_: str, branches: List[Dict[str, Any]]) -> Dict[str, Any]:
+    return {"type": "alt", "id": id_, "branches": branches}
+
+
+def branch(title: str, steps: List[Dict[str, Any]], terminal: bool = False) -> Dict[str, Any]:
+    out: Dict[str, Any] = {"title": title, "steps": steps}
+    if terminal:
+        out["terminal"] = True
+    return out
+
+
+def flow(
+    id_: str,
+    slug: str,
+    name: str,
+    summary: str,
+    source: str,
+    owner: str,
+    participants: List[Dict[str, Any]],
+    steps: List[Dict[str, Any]],
+    trigger: Optional[Dict[str, str]] = None,
+    entrypoint: str = "",
+) -> Dict[str, Any]:
+    out: Dict[str, Any] = {
+        "id": id_,
+        "slug": slug,
+        "name": name,
+        "summary": summary,
+        "source": source,
+    }
+    if trigger:
+        out["trigger"] = trigger
+    if entrypoint:
+        out["entrypoint"] = entrypoint
+    out["owner"] = owner
+    out["participants"] = participants
+    out["steps"] = steps
+    return out
+
+
+def column(name: str, type_: str, nullable: bool, pk: bool = False, fk: Optional[Dict[str, str]] = None, maps: str = "", doc: str = "") -> Dict[str, Any]:
+    out: Dict[str, Any] = {"name": name, "type": type_, "nullable": nullable}
+    if pk:
+        out["pk"] = True
+    if fk:
+        out["fk"] = fk
+    if maps:
+        out["maps"] = maps
+    if doc:
+        out["doc"] = doc
+    return out
+
+
+def table(id_: str, name: str, columns: List[Dict[str, Any]], indexes: List[Dict[str, Any]], persists: Optional[Dict[str, str]], role: str, doc: str = "") -> Dict[str, Any]:
+    out: Dict[str, Any] = {"id": id_, "name": name}
+    if doc:
+        out["doc"] = doc
+    out["columns"] = columns
+    if indexes:
+        out["indexes"] = indexes
+    if persists:
+        out["persists"] = persists
+    if role:
+        out["role"] = role
+    return out
+
+
+def store(id_: str, slug: str, name: str, kind: str, owner: str, tables: List[Dict[str, Any]], source: str) -> Dict[str, Any]:
+    out = {"id": id_, "slug": slug, "name": name, "kind": kind, "owner": owner, "tables": tables}
+    if source:
+        out["source"] = source
+    return out