@shortlink-org/portolan 0.1.0

package/plugins/fetch-git/offline.go

@@ -0,0 +1,39 @@
+package main
+
+// The only file that reads the environment, and it reads two switches.
+//
+// The plugin protocol says a plugin has no ambient state to read. That rule is
+// about facts: nothing about the estate may come from anywhere but the
+// request. Whether to open a socket is not a fact about the estate; it decides
+// whether the fetch happens, never what the fetch says, and a test asserts the
+// output is byte-identical either way.
+//
+// What git needs to reach a private forge - a credential helper, a netrc
+// entry, an ssh agent - is git's own configuration, and this plugin neither
+// reads nor passes any of it. That is also why it can never be wasm: it needs
+// a subprocess and a socket.
+
+import (
+	"os"
+	"strings"
+)
+
+// OfflineEnv turns the fetch off. Explicit, rather than inferred from a socket
+// timeout: CI sets it in one line, and a build that would otherwise depend on
+// the forge being up cannot silently start doing so again.
+const OfflineEnv = "PORTOLAN_OFFLINE"
+
+func offline() bool {
+	if strings.TrimSpace(os.Getenv(OfflineEnv)) != "" {
+		return true
+	}
+
+	// CI verifies what was committed. It never needs to reach the forge, and a
+	// fork's pull request has no credential to reach it with.
+	switch strings.ToLower(strings.TrimSpace(os.Getenv("CI"))) {
+	case "", "0", "false":
+		return false
+	default:
+		return true
+	}
+}

package/plugins/fetch-git/options.schema.json

@@ -0,0 +1,42 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["repos", "cache"],
+  "properties": {
+    "repos": {
+      "type": "array",
+      "minItems": 1,
+      "description": "The repositories to fetch, each pinned to a commit.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["repo"],
+        "properties": {
+          "repo": {
+            "type": "string",
+            "description": "Where the repository is: github.com/acme/shop, or any URL git accepts (https://, ssh://, git@host:owner/name).",
+            "examples": ["github.com/acme/shop"]
+          },
+          "commit": {
+            "type": "string",
+            "description": "The commit to fetch. A pinned fetch is byte-reproducible, which is what lets an offline run replay it from the tree. Left out, `ref` is resolved online and warned about, and refused offline."
+          },
+          "ref": {
+            "type": "string",
+            "description": "The branch or tag to resolve when there is no commit. Defaults to the remote's HEAD."
+          },
+          "paths": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Directories to copy, relative to the repository's root; the rest is left behind. Left out, the whole tree.",
+            "examples": [["services/oms", "proto"]]
+          }
+        }
+      }
+    },
+    "cache": {
+      "type": "string",
+      "description": "Where the last run's files were written, repo-relative: the same path as the step's out. An offline run replays what is there and checks it against the lock beside it."
+    }
+  }
+}

package/plugins/fetch-git/pin.go

@@ -0,0 +1,90 @@
+package main
+
+// The fragment that says where the copy came from.
+//
+// The lock beside it already names the commit, but a lock is a check and not a
+// fact anybody reads: nothing loads it, and by the time a page wants to link a
+// source line of a vendored service, the only thing left is a repository name
+// with no commit against it. So the same answer is written twice, in two
+// shapes, for two readers - `git.lock.json` for the next run of this step, and
+// a one-line catalog fragment for the estate.
+//
+// It is a fragment rather than a field the extractor fills in because the
+// extractor does not know: it is handed a directory and reads it as a pure
+// function of what is on disk, which is the whole reason fetching is a
+// separate step. What fetched it knows, so what fetched it says so.
+
+import (
+	"encoding/json"
+	"path"
+	"strings"
+
+	"github.com/shortlink-org/portolan/catalog"
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+// PinName is the fragment written beside each repository's copy. It is named
+// after the lock it sits next to, so a directory listing reads as one thing
+// the fetch wrote rather than two unrelated files.
+const PinName = "git.repo.json"
+
+// webRepo is the repository as `Service.repo` spells it - host/owner/name, the
+// way go.mod writes it - whatever spelling the manifest used.
+//
+// The lock keeps what the manifest said, because a lock is about the fetch. The
+// fragment cannot: it is matched against a service's `repo`, and a service read
+// out of a Go module has no idea whether whoever vendored it typed an ssh URL.
+func webRepo(name string) string {
+	name = strings.TrimSpace(name)
+
+	switch {
+	case strings.HasPrefix(name, "git@"):
+		// git@host:owner/name -> host/owner/name
+		host, where, _ := strings.Cut(strings.TrimPrefix(name, "git@"), ":")
+		name = host + "/" + where
+	case strings.Contains(name, "://"):
+		_, name, _ = strings.Cut(name, "://")
+		// A URL may carry a user: https://git@host/owner/name.
+		if _, after, found := strings.Cut(name, "@"); found {
+			name = after
+		}
+	}
+
+	return strings.TrimSuffix(strings.Trim(name, "/"), ".git")
+}
+
+// pin encodes the fragment for one repository at one commit.
+//
+// The empty lists are not noise: a source is a catalog, and a merge that had to
+// tell "no contexts" from "not a catalog" would be reading a shape rather than
+// a value. Written the way every generated file in this repository is written,
+// so `gen:check` compares it and never rewrites it.
+func pin(repo, commit string) (string, error) {
+	fragment := catalog.Catalog{
+		Contexts: []catalog.BoundedContext{},
+		Defs:     map[string]catalog.TypeDef{},
+		Flows:    []catalog.Flow{},
+		Adrs:     []catalog.Adr{},
+		Repos:    []catalog.RepoPin{{Repo: webRepo(repo), Commit: commit}},
+	}
+
+	out, err := json.MarshalIndent(fragment, "", "  ")
+	if err != nil {
+		return "", err
+	}
+
+	return string(out) + "\n", nil
+}
+
+// emitPin writes the fragment into the repository's own directory, beside the
+// lock, so a vendored copy stays self-describing: the files, the statement of
+// where they came from, and the one fact the catalog needs out of it.
+func emitPin(b *plugin.Builder, dir, repo, commit string) error {
+	fragment, err := pin(repo, commit)
+	if err != nil {
+		return err
+	}
+	b.File(path.Join(dir, PinName), fragment)
+
+	return nil
+}

package/plugins/fetch-git/pin_test.go

@@ -0,0 +1,74 @@
+package main
+
+import (
+	"encoding/json"
+	"testing"
+
+	"github.com/shortlink-org/portolan/catalog"
+)
+
+// A pin is matched against a service's `repo`, which is however go.mod spells
+// it. Whoever wrote the manifest may have spelled the same repository four
+// other ways, and all five have to arrive at one string or the link is not
+// built.
+func TestWebRepoIsHowGoModSpellsIt(t *testing.T) {
+	const want = "github.com/acme/shop"
+
+	for _, spelling := range []string{
+		"github.com/acme/shop",
+		"github.com/acme/shop/",
+		"github.com/acme/shop.git",
+		"https://github.com/acme/shop",
+		"https://github.com/acme/shop.git",
+		"ssh://git@github.com/acme/shop.git",
+		"git@github.com:acme/shop.git",
+		"  github.com/acme/shop  ",
+	} {
+		if got := webRepo(spelling); got != want {
+			t.Errorf("webRepo(%q) = %q, want %q", spelling, got, want)
+		}
+	}
+}
+
+// The fragment has to survive the round trip through the mirror, because that
+// is the only thing that reads it: a shape the catalog does not recognise is a
+// file the host writes, commits and never uses.
+func TestPinIsACatalogWithOneRepo(t *testing.T) {
+	out, err := pin("git@github.com:acme/shop.git", "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0")
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var parsed catalog.Catalog
+	if err := json.Unmarshal([]byte(out), &parsed); err != nil {
+		t.Fatalf("fragment is not a catalog: %v", err)
+	}
+	if len(parsed.Repos) != 1 {
+		t.Fatalf("repos = %+v, want one", parsed.Repos)
+	}
+	if parsed.Repos[0].Repo != "github.com/acme/shop" {
+		t.Errorf("repo = %q", parsed.Repos[0].Repo)
+	}
+	if parsed.Repos[0].Commit != "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0" {
+		t.Errorf("commit = %q", parsed.Repos[0].Commit)
+	}
+	if out[len(out)-1] != '\n' {
+		t.Error("fragment does not end in a newline, like every other generated file here")
+	}
+}
+
+// Determinism, the second of the three obligations: the same fetch writes the
+// same bytes, or `gen:check` reports drift on a run that changed nothing.
+func TestPinIsStable(t *testing.T) {
+	first, err := pin("github.com/acme/shop", "c1d2e3f")
+	if err != nil {
+		t.Fatal(err)
+	}
+	second, err := pin("github.com/acme/shop", "c1d2e3f")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if first != second {
+		t.Errorf("two runs wrote different bytes:\n%s\n%s", first, second)
+	}
+}

package/plugins/gen-backstage/describe.go

@@ -0,0 +1,17 @@
+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: "gen-backstage", Summary: "Exports contexts, services, APIs, stores and schema modules as a Backstage catalog.",
+		Phases: []string{plugin.PhaseGenerate}, Options: optionsSchema,
+	}
+}

package/plugins/gen-backstage/main.go

@@ -0,0 +1,22 @@
+package main
+
+import (
+	"fmt"
+	"io"
+	"os"
+
+	"github.com/shortlink-org/portolan/plugin"
+)
+
+func main() {
+	if err := run(os.Stdin, os.Stdout); err != nil {
+		fmt.Fprintln(os.Stderr, "portolan-gen-backstage:", 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) {
+		return render(req, opts)
+	})
+}

package/plugins/gen-backstage/options.schema.json

@@ -0,0 +1,30 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "domain": {
+      "type": "string",
+      "description": "Backstage metadata.name for the domain containing the exported systems.",
+      "default": "architecture"
+    },
+    "domainTitle": {
+      "type": "string",
+      "description": "Human-readable title of the Backstage domain.",
+      "default": "Architecture"
+    },
+    "owner": {
+      "type": "string",
+      "description": "Fallback Backstage owner for entities without a CODEOWNERS handle.",
+      "default": "architecture"
+    },
+    "lifecycle": {
+      "type": "string",
+      "description": "Lifecycle written on Backstage Components and APIs.",
+      "default": "production"
+    },
+    "sourceBaseUrl": {
+      "type": "string",
+      "description": "Stable forge tree URL used for Backstage source-location annotations."
+    }
+  }
+}