@shortlink-org/portolan 0.2.3 → 0.3.0

package/catalog/roundtrip_test.go

@@ -0,0 +1,203 @@
+package catalog
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sort"
+	"testing"
+)
+
+// TestRoundTrip is what holds this package to src/catalog.ts.
+//
+// Every real catalog in the repository is unmarshalled into these structs and
+// marshalled straight back out. Anything the mirror does not know about is
+// dropped on the way in and missing on the way out, so a field added to the
+// TypeScript and forgotten here fails as a named path rather than as a blank
+// section in somebody's generated documentation.
+//
+// The comparison is semantic: key order differs by construction, and an
+// optional list that was written as [] is the same fact as one left out.
+func TestRoundTrip(t *testing.T) {
+	files, err := filepath.Glob("../data/*.json")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(files) == 0 {
+		t.Fatal("no catalogs under ../data - this test proves nothing without one")
+	}
+
+	for _, path := range files {
+		t.Run(filepath.Base(path), func(t *testing.T) {
+			raw, err := os.ReadFile(path)
+			if err != nil {
+				t.Fatal(err)
+			}
+
+			var before any
+			if err := json.Unmarshal(raw, &before); err != nil {
+				t.Fatalf("source is not JSON: %v", err)
+			}
+
+			var parsed Catalog
+			if err := json.Unmarshal(raw, &parsed); err != nil {
+				t.Fatalf("catalog does not fit the mirror: %v", err)
+			}
+
+			out, err := json.Marshal(&parsed)
+			if err != nil {
+				t.Fatalf("mirror does not marshal: %v", err)
+			}
+
+			var after any
+			if err := json.Unmarshal(out, &after); err != nil {
+				t.Fatal(err)
+			}
+
+			diffs := compare("catalog", normalize(before), normalize(after))
+			if len(diffs) == 0 {
+				return
+			}
+
+			shown := diffs
+			if len(shown) > 20 {
+				shown = shown[:20]
+			}
+			for _, d := range shown {
+				t.Error(d)
+			}
+			if len(diffs) > len(shown) {
+				t.Errorf("... and %d more", len(diffs)-len(shown))
+			}
+		})
+	}
+}
+
+func TestChannelMessageWireFormatRoundTrip(t *testing.T) {
+	before := ChannelMessage{
+		Name: "cart.BasketCreated", Direction: ChannelSend,
+		Encoding: "msgpack", ContentType: "application/msgpack",
+	}
+	raw, err := json.Marshal(before)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var after ChannelMessage
+	if err := json.Unmarshal(raw, &after); err != nil {
+		t.Fatal(err)
+	}
+	if after.Encoding != before.Encoding || after.ContentType != before.ContentType {
+		t.Fatalf("wire format changed: %+v", after)
+	}
+}
+
+// normalize drops keys whose value carries no information. An optional list
+// written as [] and one left out entirely say the same thing, and holding the
+// mirror to which of the two it produces would test encoding/json rather than
+// the shape.
+func normalize(v any) any {
+	switch t := v.(type) {
+	case map[string]any:
+		out := make(map[string]any, len(t))
+		for k, item := range t {
+			switch inner := item.(type) {
+			case []any:
+				if len(inner) == 0 {
+					continue
+				}
+			case map[string]any:
+				if len(inner) == 0 {
+					continue
+				}
+			}
+			out[k] = normalize(item)
+		}
+
+		return out
+	case []any:
+		out := make([]any, len(t))
+		for i, item := range t {
+			out[i] = normalize(item)
+		}
+
+		return out
+	default:
+		return v
+	}
+}
+
+// compare walks both trees together and names every place they part, as a path
+// a reader can find in the file.
+func compare(path string, before, after any) []string {
+	switch b := before.(type) {
+	case map[string]any:
+		a, ok := after.(map[string]any)
+		if !ok {
+			return []string{fmt.Sprintf("%s: object in the source, %T after the round trip", path, after)}
+		}
+
+		var diffs []string
+		for _, key := range sortedKeys(b, a) {
+			bv, inSource := b[key]
+			av, inMirror := a[key]
+			switch {
+			case inSource && !inMirror:
+				diffs = append(diffs, fmt.Sprintf("%s.%s: dropped by the mirror (%s)", path, key, brief(bv)))
+			case !inSource && inMirror:
+				diffs = append(diffs, fmt.Sprintf("%s.%s: invented by the mirror (%s)", path, key, brief(av)))
+			default:
+				diffs = append(diffs, compare(path+"."+key, bv, av)...)
+			}
+		}
+
+		return diffs
+	case []any:
+		a, ok := after.([]any)
+		if !ok {
+			return []string{fmt.Sprintf("%s: list in the source, %T after the round trip", path, after)}
+		}
+		if len(b) != len(a) {
+			return []string{fmt.Sprintf("%s: %d entries in the source, %d after the round trip", path, len(b), len(a))}
+		}
+
+		var diffs []string
+		for i := range b {
+			diffs = append(diffs, compare(fmt.Sprintf("%s[%d]", path, i), b[i], a[i])...)
+		}
+
+		return diffs
+	default:
+		if before != after {
+			return []string{fmt.Sprintf("%s: %s became %s", path, brief(before), brief(after))}
+		}
+
+		return nil
+	}
+}
+
+func sortedKeys(maps ...map[string]any) []string {
+	seen := map[string]bool{}
+	for _, m := range maps {
+		for k := range m {
+			seen[k] = true
+		}
+	}
+
+	keys := make([]string, 0, len(seen))
+	for k := range seen {
+		keys = append(keys, k)
+	}
+	sort.Strings(keys)
+
+	return keys
+}
+
+func brief(v any) string {
+	s := fmt.Sprintf("%v", v)
+	if len(s) > 60 {
+		return s[:57] + "..."
+	}
+
+	return s
+}

package/catalog/via_test.go

@@ -0,0 +1,38 @@
+package catalog
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+// TestEdgeViaRoundTrip pins the one field no committed catalog carries: `via`
+// is written by the host after the merge, so the roundtrip over data/*.json
+// never sees it, and the mirror would drop it silently on the way to a
+// generator.
+func TestEdgeViaRoundTrip(t *testing.T) {
+	in := `{"service":"payments.ledger","status":"declared","via":{"flow":"order-accepted","step":"a3"}}`
+
+	var c EventConsumer
+	if err := json.Unmarshal([]byte(in), &c); err != nil {
+		t.Fatal(err)
+	}
+	if c.Via == nil || c.Via.Flow != "order-accepted" || c.Via.Step != "a3" {
+		t.Fatalf("via not read: %+v", c.Via)
+	}
+
+	out, err := json.Marshal(&c)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(out) != in {
+		t.Fatalf("round trip changed the consumer:\n got %s\nwant %s", out, in)
+	}
+
+	var call RpcCall
+	if err := json.Unmarshal([]byte(`{"id":"x/Y","peer":"p","status":"declared","source":"s"}`), &call); err != nil {
+		t.Fatal(err)
+	}
+	if call.Via != nil {
+		t.Fatalf("a call without via must round-trip without one: %+v", call.Via)
+	}
+}

package/cli/init.test.mjs

@@ -4,7 +4,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { afterEach, beforeAll, describe, expect, it } from "vitest";
 
-import { InitError, defaultAnswers, init, nextStep } from "./init.mjs";
+import { InitError, defaultAnswers, init, nextStep, toolchainFor } from "./init.mjs";
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const created = [];
@@ -36,6 +36,11 @@ const goService = {
 };
 
 describe("init with defaults", () => {
+  it("declares Go only for the typed HTTP client analyzer", () => {
+    expect(toolchainFor("http-clients")).toMatchObject({ command: "go", label: "Go", missing: false });
+    expect(toolchainFor("go-domain")).toBeNull();
+  });
+
   it("prints runnable next commands with and without package scripts", () => {
     expect(nextStep(false, true)).toBe("Next: npm run architecture:gen && npm run architecture");
     expect(nextStep(true, true)).toBe("Generating; then: npm run architecture");

package/cli/portolan.mjs

@@ -264,6 +264,14 @@ export async function prepareSite(workspace) {
   };
   writeFileSync(resolve(stage, "portolan.json"), `${JSON.stringify(stagedManifest, null, 2)}\n`);
 
+  // The browser imports flattened paths, but provenance belongs to the
+  // original files in the workspace's history. Keep that correspondence
+  // outside the fragments so staging never invents a new source stamp.
+  mkdirSync(resolve(stage, ".portolan"), { recursive: true });
+  writeFileSync(resolve(stage, ".portolan/source-paths.json"), `${JSON.stringify(Object.fromEntries(
+    [...flattened].map(([source, staged]) => [staged, source]),
+  ), null, 2)}\n`);
+
   const modules = dependencyRoot();
   symlinkSync(modules, resolve(stage, "node_modules"), process.platform === "win32" ? "junction" : "dir");
   return stage;

package/cli/portolan.test.mjs

@@ -1,9 +1,13 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { execFileSync } from "node:child_process";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { afterEach, describe, expect, it } from "vitest";
 
 import { prepareSite, VERSION } from "./portolan.mjs";
+import { provenancePlugin, PROVENANCE_MODULE } from "../scripts/provenance.mjs";
+import { mergeCatalogs } from "../src/merge.ts";
+import { validateCatalog } from "../src/catalog.ts";
 
 const roots = [];
 afterEach(() => {
@@ -11,6 +15,51 @@ afterEach(() => {
 });
 
 describe("site staging", () => {
+  it("keeps original Git provenance for flattened sources in every catalog profile", async () => {
+    const root = mkdtempSync(join(tmpdir(), "portolan-staged-provenance-"));
+    roots.push(root);
+    const fragment = (id) => JSON.stringify({ contexts: [{ id, slug: id, name: id, services: [] }], defs: {}, flows: [], adrs: [] });
+    mkdirSync(join(root, "data"));
+    mkdirSync(join(root, "examples/shop/portolan"), { recursive: true });
+    writeFileSync(join(root, "data/self.json"), fragment("portolan"));
+    writeFileSync(join(root, "examples/shop/portolan/domain.json"), fragment("shop"));
+    // The example is profile-only: provenance must cover every staged source.
+    writeFileSync(join(root, "portolan.json"), JSON.stringify({
+      sources: ["data/*.json"],
+      catalogs: [
+        { id: "portolan", title: "Portolan", contexts: ["portolan"], projects: [], sources: ["data/*.json"] },
+        { id: "example", title: "Example", contexts: ["shop"], projects: [], sources: ["examples/*/portolan/*.json"] },
+      ],
+    }));
+    const git = (...args) => execFileSync("git", ["-C", root, ...args], {
+      encoding: "utf8",
+      env: { ...process.env, GIT_AUTHOR_NAME: "Test", GIT_AUTHOR_EMAIL: "test@example.com", GIT_COMMITTER_NAME: "Test", GIT_COMMITTER_EMAIL: "test@example.com", GIT_AUTHOR_DATE: "2026-03-03T03:00:00Z", GIT_COMMITTER_DATE: "2026-03-03T03:00:00Z" },
+    }).trim();
+    git("init", "-q");
+    git("add", ".");
+    git("-c", "commit.gpgsign=false", "commit", "-qm", "catalogs");
+    const commit = git("rev-parse", "--short=7", "HEAD");
+
+    const stage = await prepareSite(root);
+    const plugin = provenancePlugin(root);
+    plugin.configResolved({ root: stage });
+    const module = plugin.load(plugin.resolveId(PROVENANCE_MODULE));
+    const stamps = JSON.parse(module.slice("export default ".length).trim().replace(/;$/, ""));
+    const manifest = JSON.parse(readFileSync(join(stage, "portolan.json"), "utf8"));
+    for (const [i, profile] of manifest.catalogs.entries()) {
+      const sources = profile.sources.map((path) => ({
+        path, catalog: JSON.parse(readFileSync(join(stage, path), "utf8")), stamp: stamps[path],
+      }));
+      expect(sources).toHaveLength(1);
+      expect(sources[0].catalog.generatedAt).toBeUndefined();
+      // The stamp is the workspace file's, and it says which file: the path a
+      // project's root is a prefix of, which the flattened name is not.
+      expect(sources[0].stamp).toEqual({ commit, generatedAt: "2026-03-03T03:00:00Z", source: i === 0 ? "data/self.json" : "examples/shop/portolan/domain.json" });
+      const catalog = validateCatalog(mergeCatalogs(sources).catalog);
+      expect(catalog.contexts.map((context) => context.id)).toEqual([i === 0 ? "portolan" : "shop"]);
+    }
+  });
+
   it("stages a deterministic source for an intentional empty workspace", async () => {
     const root = mkdtempSync(join(tmpdir(), "portolan-empty-site-"));
     roots.push(root);

package/go.mod

@@ -0,0 +1,14 @@
+module github.com/shortlink-org/portolan
+
+go 1.27.0
+
+require (
+	github.com/pgplex/pgparser v0.2.0
+	golang.org/x/tools v0.50.0
+	gopkg.in/yaml.v3 v3.0.1
+)
+
+require (
+	golang.org/x/mod v0.41.0 // indirect
+	golang.org/x/sync v0.23.0 // indirect
+)

package/go.sum

@@ -0,0 +1,20 @@
+github.com/google/go-cmp v0.6.0 h1:ofyhxvXcZhMsU5ulbFiLKl/XBFqE1GSq7atu8tAmTRI=
+github.com/google/go-cmp v0.6.0/go.mod h1:17dUlkBOakJ0+DkrSSNjCkIjxS6bF9zb3elmeNGIjoY=
+github.com/pgplex/pgparser v0.2.0 h1:BB7I/Mrwetiw07PTq/AlXcKfajlCwoJfwB7KZ7V9irI=
+github.com/pgplex/pgparser v0.2.0/go.mod h1:DWhK7oZJn/16KTFeOQ+mk78+sRnEYya1XPghIoP9NFU=
+golang.org/x/mod v0.39.0 h1:UF5zwQdCRRUpHfyPwr7d4UrGiVeldIsogtzWVnczL74=
+golang.org/x/mod v0.39.0/go.mod h1:bvIbwjQ0HUFFf5AKukeeYQG4ZBUG9yxQbR9aEweIwYY=
+golang.org/x/mod v0.41.0 h1:qJmnOUb4YB+FsEuM3HcWucdZASCPGhsX6uljO6pog0c=
+golang.org/x/mod v0.41.0/go.mod h1:Ek9pY8RKWXwsWvd3rQiHYtMqkjSUV+s1Rj7j4H5Ur6o=
+golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
+golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
+golang.org/x/sync v0.23.0 h1:KameEIfc1IkluZyXWLn39Wd4tURc6GbCiISGiZm2bQk=
+golang.org/x/sync v0.23.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
+golang.org/x/tools v0.49.0 h1:3NI7VXzL9+1WZD52Dx2ttoPwD5DWrFGpl9mFZDlmisI=
+golang.org/x/tools v0.49.0/go.mod h1:SJNXV9DBKT0UbdttsQjbfJlAE/q+y36++zo3uL3N0Oo=
+golang.org/x/tools v0.50.0 h1:c2ifzfcuY7L90lZ2aKd8S4K2NpASF08SZx9ZuJkHmSU=
+golang.org/x/tools v0.50.0/go.mod h1:7ulVMw3831Mwi5EZD6RomGyffr4VFjuNYXf2BbCEAV0=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405 h1:yhCVgyC4o1eVCa2tZl7eS0r+SDo693bJlVdllGtEeKM=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
+gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

package/internal/gocall/README.md

@@ -0,0 +1,19 @@
+# Shared typed Go call facts
+
+`Analyze(ctx, Options)` loads a project's Go packages and returns source-backed
+call edges without depending on HTTP or the catalog schema. Positions are
+relative to the input root and include columns. Functions retain their lexical
+parents so each consumer can decide how to display closures.
+
+Edges distinguish direct static calls from possible targets computed by VTA.
+Possible targets must not be treated as proof that every implementation runs.
+Consumers should retain ambiguity when assembly cannot narrow the target.
+Package errors produce a partial result with diagnostics when independent
+packages remain usable. If none can be analyzed, the caller receives an error.
+
+The first consumer is `internal/gohttp`: its existing native sidecar adapts
+these facts to its syntax index. Other extractors can adopt this API without
+copying the package loader or depending on the HTTP scanner. The syntax-only
+WASI extractors remain toolchain-free; they must not import this native loader.
+Native callers must bound process execution because SSA/VTA cannot be interrupted
+by a context while computing. The context does bound package loading.

package/internal/gocall/analyze.go

@@ -0,0 +1,189 @@
+// Package gocall supplies source-backed, typed call facts to native Go
+// extractors. It has no knowledge of HTTP, domain layouts or catalog lanes.
+package gocall
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+	"sort"
+	"strings"
+
+	"golang.org/x/tools/go/callgraph"
+	"golang.org/x/tools/go/callgraph/vta"
+	"golang.org/x/tools/go/packages"
+	"golang.org/x/tools/go/ssa"
+	"golang.org/x/tools/go/ssa/ssautil"
+)
+
+// Position is relative to the analysis root. Column distinguishes call sites
+// on the same line. Empty File means a declaration outside the source root.
+type Position struct {
+	File   string
+	Line   int
+	Column int
+}
+
+type Definition struct {
+	Name     string
+	Position Position
+}
+
+// Function retains lexical parents so a consumer may map a closure to its
+// enclosing declaration without making that policy part of the shared graph.
+type Function struct {
+	ID          string
+	Definitions []Definition
+}
+
+type Kind string
+
+const (
+	Static   Kind = "static"
+	Possible Kind = "possible"
+)
+
+// Edge records a static target or a VTA candidate. A Possible edge is not
+// evidence that the target executes in a particular runtime scenario.
+type Edge struct {
+	Caller Function
+	Callee Function
+	Site   Position
+	Kind   Kind
+}
+
+type Diagnostic struct {
+	Package string
+	Message string
+}
+
+func (d Diagnostic) String() string { return d.Package + ": " + d.Message }
+
+type Result struct {
+	Edges       []Edge
+	Diagnostics []Diagnostic
+	// Complete is false when package errors forced a partial graph.
+	Complete bool
+}
+
+type Options struct {
+	Root       string
+	Patterns   []string
+	BuildFlags []string
+}
+
+// Analyze respects the caller's deadline while loading packages. Native
+// consumers also bound the whole process, since SSA/VTA do not accept a context.
+// Broken packages and their dependents are excluded; independent packages
+// still contribute facts, accompanied by diagnostics.
+func Analyze(ctx context.Context, opts Options) (Result, error) {
+	root, err := filepath.Abs(opts.Root)
+	if err != nil {
+		return Result{}, err
+	}
+	patterns := opts.Patterns
+	if len(patterns) == 0 {
+		patterns = []string{"./..."}
+	}
+	flags := append([]string{"-mod=readonly"}, opts.BuildFlags...)
+	loaded, err := packages.Load(&packages.Config{
+		Context: ctx, Dir: root, Mode: packages.LoadSyntax, Tests: false, BuildFlags: flags,
+	}, patterns...)
+	if err != nil {
+		return Result{}, err
+	}
+	if err := ctx.Err(); err != nil {
+		return Result{}, err
+	}
+	result := Result{Complete: true}
+	var usable []*packages.Package
+	for _, pkg := range loaded {
+		if len(pkg.Errors) > 0 || pkg.IllTyped {
+			result.Complete = false
+			if len(pkg.Errors) == 0 {
+				result.Diagnostics = append(result.Diagnostics, Diagnostic{pkg.PkgPath, "package is ill-typed"})
+			}
+			for _, problem := range pkg.Errors {
+				result.Diagnostics = append(result.Diagnostics, Diagnostic{pkg.PkgPath, problem.Error()})
+			}
+			continue
+		}
+		usable = append(usable, pkg)
+	}
+	sort.Slice(result.Diagnostics, func(i, j int) bool { return result.Diagnostics[i].String() < result.Diagnostics[j].String() })
+	if len(usable) == 0 {
+		if len(result.Diagnostics) > 0 {
+			return result, fmt.Errorf("no usable Go packages: %s", result.Diagnostics[0].String())
+		}
+		return result, fmt.Errorf("no Go packages found")
+	}
+	program, _ := ssautil.Packages(usable, ssa.InstantiateGenerics)
+	program.Build()
+	if err := ctx.Err(); err != nil {
+		return result, err
+	}
+	functions := ssautil.AllFunctions(program)
+	if len(functions) == 0 {
+		return result, fmt.Errorf("SSA program contains no source functions")
+	}
+	position := func(filename string, line, column int) Position {
+		rel, err := filepath.Rel(root, filename)
+		if filename == "" || line == 0 || err != nil || rel == ".." || strings.HasPrefix(rel, ".."+string(filepath.Separator)) {
+			return Position{}
+		}
+		return Position{filepath.ToSlash(rel), line, column}
+	}
+	function := func(fn *ssa.Function) Function {
+		out := Function{ID: fn.String()}
+		for candidate := fn; candidate != nil; candidate = candidate.Parent() {
+			pos := program.Fset.Position(candidate.Pos())
+			if at := position(pos.Filename, pos.Line, pos.Column); at.File != "" {
+				out.Definitions = append(out.Definitions, Definition{candidate.Name(), at})
+			}
+		}
+		return out
+	}
+	graph := vta.CallGraph(functions, nil)
+	seen := map[string]bool{}
+	err = callgraph.GraphVisitEdges(graph, func(edge *callgraph.Edge) error {
+		if err := ctx.Err(); err != nil {
+			return err
+		}
+		caller, callee := function(edge.Caller.Func), function(edge.Callee.Func)
+		if len(caller.Definitions) == 0 || len(callee.Definitions) == 0 {
+			return nil
+		}
+		pos := program.Fset.Position(edge.Pos())
+		site := position(pos.Filename, pos.Line, pos.Column)
+		kind := Possible
+		if edge.Site != nil && edge.Site.Common().StaticCallee() != nil {
+			kind = Static
+		}
+		key := fmt.Sprintf("%s\x00%d:%d\x00%s\x00%s", site.File, site.Line, site.Column, caller.ID, callee.ID)
+		if !seen[key] {
+			seen[key] = true
+			result.Edges = append(result.Edges, Edge{caller, callee, site, kind})
+		}
+		return nil
+	})
+	if err != nil {
+		return result, err
+	}
+	sort.Slice(result.Edges, func(i, j int) bool {
+		a, b := result.Edges[i], result.Edges[j]
+		if a.Site.File != b.Site.File {
+			return a.Site.File < b.Site.File
+		}
+		if a.Site.Line != b.Site.Line {
+			return a.Site.Line < b.Site.Line
+		}
+		if a.Site.Column != b.Site.Column {
+			return a.Site.Column < b.Site.Column
+		}
+		if a.Caller.ID != b.Caller.ID {
+			return a.Caller.ID < b.Caller.ID
+		}
+		return a.Callee.ID < b.Callee.ID
+	})
+	return result, nil
+}