@shortlink-org/portolan 0.2.3 → 0.3.0

package/internal/goscan/names.go

@@ -0,0 +1,52 @@
+package goscan
+
+import "strings"
+
+// LastSegment is what follows the last dot: the name off a type key, the
+// event off a wire name.
+func LastSegment(value string) string {
+	if at := strings.LastIndex(value, "."); at >= 0 {
+		return value[at+1:]
+	}
+	return value
+}
+
+// Slug is a value as an identifier in a URL or a catalog id: lower case,
+// runs of anything else collapsed to one dash, none at the ends.
+func Slug(value string) string {
+	value = strings.ToLower(strings.TrimSpace(value))
+	var out strings.Builder
+	dash := false
+	for _, r := range value {
+		if r >= 'a' && r <= 'z' || r >= '0' && r <= '9' {
+			out.WriteRune(r)
+			dash = false
+		} else if out.Len() > 0 && !dash {
+			out.WriteByte('-')
+			dash = true
+		}
+	}
+	return strings.TrimSuffix(out.String(), "-")
+}
+
+// Title is a slug or an identifier as words: split on dash, underscore and
+// dot, each capitalised.
+func Title(value string) string {
+	parts := strings.FieldsFunc(value, func(r rune) bool { return r == '-' || r == '_' || r == '.' })
+	for i := range parts {
+		if parts[i] != "" {
+			parts[i] = strings.ToUpper(parts[i][:1]) + parts[i][1:]
+		}
+	}
+	return strings.Join(parts, " ")
+}
+
+// FirstNonEmpty is the first value that is more than whitespace.
+func FirstNonEmpty(values ...string) string {
+	for _, value := range values {
+		if strings.TrimSpace(value) != "" {
+			return value
+		}
+	}
+	return ""
+}

package/internal/goscan/parse_test.go

@@ -0,0 +1,11 @@
+package goscan
+
+import (
+	"go/ast"
+	"go/parser"
+)
+
+// parseExpr is go/parser's, named here so a test reads as a table.
+func parseExpr(src string) (ast.Expr, error) {
+	return parser.ParseExpr(src)
+}

package/internal/goscan/source.go

@@ -0,0 +1,37 @@
+package goscan
+
+import (
+	"fmt"
+	"go/ast"
+)
+
+// Source is a place in the tree, the way the catalog cites one: the file
+// relative to the root, and the line when there is one.
+type Source struct {
+	File string
+	Line int
+}
+
+func (s Source) String() string {
+	if s.Line == 0 {
+		return s.File
+	}
+	return fmt.Sprintf("%s:%d", s.File, s.Line)
+}
+
+// File is one parsed file: its path under the root, the import path of its
+// package, its imports by local name, and the syntax.
+type File struct {
+	Generated bool
+	Name      string
+	Pkg       string
+	Imports   map[string]string
+	Node      *ast.File
+}
+
+// ConstExpr is a constant as it was declared: the expression, and the file it
+// is in, since the expression's names mean what that file's imports say.
+type ConstExpr struct {
+	Expr ast.Expr
+	File *File
+}

package/internal/goscan/tree.go

@@ -0,0 +1,284 @@
+// Package goscan reads a Go source tree the way the extractors need it: every
+// non-test, non-generated file parsed once, each with the import path of its
+// package and its imports by local name, and the string constants of the tree
+// indexed so that a topic, a queue or a subject named by a constant resolves to
+// the literal behind it.
+//
+// It is the part of a Go extractor that has nothing to do with what the
+// extractor is looking for. River, Watermill and go-nats read the tree this
+// way, and the next Go extractor should not have to copy it a fourth time.
+//
+// Index, over a Tree, is the second shared part: the structs with their field
+// types and tag defaults, the interfaces by method name, and every function
+// with its parameters and results, so that a value - a subject, a topic, a
+// queue, a job type - is followed through locals, fields, constructors and
+// parameters up to the callers that pass it, the same way in each extractor.
+package goscan
+
+import (
+	"fmt"
+	"go/ast"
+	"go/build"
+	"go/parser"
+	"go/token"
+	"io/fs"
+	"os"
+	"path"
+	"path/filepath"
+	"runtime"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// ReadOptions controls a source snapshot. Generated declarations can be used
+// for type/contract resolution without treating them as handwritten behavior.
+type ReadOptions struct {
+	IncludeGenerated bool
+	AllowPartial     bool
+	GOOS             string
+	GOARCH           string
+	Tags             []string
+	// Directories restricts parsing to these module-relative directories.
+	Directories []string
+}
+
+// Tree is one Go module's source, read once.
+type Tree struct {
+	Diagnostics []string
+	ByDir       map[string][]*File
+	Options     ReadOptions
+
+	Root   string
+	Module string
+	Fset   *token.FileSet
+	// Files in path order, so that whatever is read off them comes out in the
+	// same order every run.
+	Files []*File
+	// Constants is every constant of the tree by "<import path>.<Name>", as
+	// the expression that declared it, so a constant defined through another
+	// is followed rather than copied.
+	Constants map[string]ConstExpr
+	// Foreign is what an identifier from a package outside the tree is worth,
+	// when the extractor knows: river.QueueDefault is "default", and nothing
+	// in the tree says so. Nil when there is nothing to say.
+	Foreign func(importPath, name string) (string, bool)
+}
+
+// Read parses the tree under root. Test files, generated files, vendored
+// code and dot-directories are left out: they are not what the service
+// says about itself.
+func Read(root string) (*Tree, error) { return ReadWithOptions(root, ReadOptions{}) }
+
+func ReadWithOptions(root string, options ReadOptions) (*Tree, error) {
+	root = filepath.Clean(root)
+	t := &Tree{Root: root, Module: ModulePath(root), Fset: token.NewFileSet(), Constants: map[string]ConstExpr{}, ByDir: map[string][]*File{}, Options: options}
+	buildContext := build.Default
+	if options.GOOS != "" {
+		buildContext.GOOS = options.GOOS
+	} else if target := os.Getenv("GOOS"); target != "" {
+		buildContext.GOOS = target
+	}
+	if options.GOARCH != "" {
+		buildContext.GOARCH = options.GOARCH
+	} else if target := os.Getenv("GOARCH"); target != "" {
+		buildContext.GOARCH = target
+	}
+	buildContext.BuildTags = append([]string(nil), options.Tags...)
+	// The WASI host supplies the target platform. Never silently analyze the
+	// wasip1 runtime's file set when running the syntax extractor as a plugin.
+	matchBuild := runtime.GOOS != "wasip1" || options.GOOS != "" || os.Getenv("GOOS") != ""
+	allowed := map[string]bool{}
+	for _, dir := range options.Directories {
+		allowed[filepath.ToSlash(filepath.Clean(dir))] = true
+	}
+
+	var names []string
+	err := filepath.WalkDir(root, func(name string, entry fs.DirEntry, err error) error {
+		if err != nil {
+			return err
+		}
+		if entry.IsDir() {
+			if name != root {
+				if _, err := os.Stat(filepath.Join(name, "go.mod")); err == nil {
+					return filepath.SkipDir
+				}
+			}
+			if name != root && strings.HasPrefix(entry.Name(), ".") {
+				return filepath.SkipDir
+			}
+			switch entry.Name() {
+			case ".git", ".portolan", "node_modules", "vendor", "testdata":
+				if name != root {
+					return filepath.SkipDir
+				}
+			}
+			return nil
+		}
+		base := entry.Name()
+		if !strings.HasSuffix(base, ".go") || strings.HasSuffix(base, "_test.go") {
+			return nil
+		}
+		rel, _ := filepath.Rel(root, filepath.Dir(name))
+		if len(allowed) > 0 && !allowed[filepath.ToSlash(rel)] {
+			return nil
+		}
+		if matchBuild {
+			match, err := buildContext.MatchFile(filepath.Dir(name), base)
+			if err != nil {
+				return err
+			}
+			if !match {
+				return nil
+			}
+		}
+		if !options.IncludeGenerated && generatedName(base) {
+			return nil
+		}
+		names = append(names, name)
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	sort.Strings(names)
+
+	for _, name := range names {
+		node, err := parser.ParseFile(t.Fset, name, nil, parser.ParseComments)
+		if err != nil {
+			if !options.AllowPartial {
+				return nil, fmt.Errorf("parse %s: %w", name, err)
+			}
+			t.Diagnostics = append(t.Diagnostics, fmt.Sprintf("parse %s: %v", name, err))
+			continue
+		}
+		generated := IsGenerated(name, node)
+		if generated && !options.IncludeGenerated {
+			continue
+		}
+		rel, _ := filepath.Rel(root, name)
+		t.Files = append(t.Files, &File{
+			Name:      filepath.ToSlash(rel),
+			Generated: generated,
+			Pkg:       t.PackagePath(filepath.Dir(name)),
+			Imports:   ImportsOf(node),
+			Node:      node,
+		})
+	}
+	// Index actual local package names after all declarations are known.
+	namesByImport := map[string]string{}
+	for _, file := range t.Files {
+		namesByImport[file.Pkg] = file.Node.Name.Name
+		dir := filepath.ToSlash(filepath.Dir(file.Name))
+		t.ByDir[dir] = append(t.ByDir[dir], file)
+	}
+	for _, file := range t.Files {
+		for _, spec := range file.Node.Imports {
+			if spec.Name != nil {
+				continue
+			}
+			imported, _ := strconv.Unquote(spec.Path.Value)
+			if name := namesByImport[imported]; name != "" {
+				delete(file.Imports, path.Base(imported))
+				file.Imports[name] = imported
+			}
+		}
+	}
+	t.indexConstants()
+
+	return t, nil
+}
+
+// PackagePath is the import path of the package in dir: the module path
+// with the directory under it.
+func (t *Tree) PackagePath(dir string) string {
+	rel, err := filepath.Rel(t.Root, dir)
+	if err != nil || rel == "." {
+		return t.Module
+	}
+	return strings.TrimSuffix(t.Module, "/") + "/" + filepath.ToSlash(rel)
+}
+
+// At is where a node is, relative to the root.
+func (t *Tree) At(pos token.Pos) Source {
+	position := t.Fset.Position(pos)
+	rel, err := filepath.Rel(t.Root, position.Filename)
+	if err != nil {
+		rel = position.Filename
+	}
+	return Source{File: filepath.ToSlash(rel), Line: position.Line}
+}
+
+// ModulePath is what go.mod under root calls the module; the cleaned root
+// when there is no go.mod to ask.
+func ModulePath(root string) string {
+	data, err := os.ReadFile(filepath.Join(root, "go.mod"))
+	if err == nil {
+		for _, line := range strings.Split(string(data), "\n") {
+			if value, ok := strings.CutPrefix(strings.TrimSpace(line), "module "); ok {
+				return strings.TrimSpace(value)
+			}
+		}
+	}
+	return filepath.ToSlash(filepath.Clean(root))
+}
+
+// ImportsOf is a file's imports by the name the file uses for them: the alias
+// when there is one, the last path segment when there is not. Blank and dot
+// imports keep the segment, since nothing in the file refers to them by name.
+//
+// A segment with a dot in it - `nats.go`, `yaml.v3` - is not a Go identifier,
+// and the package behind it is called by what comes before the dot; that name
+// is recorded too, since it is the one the file uses.
+func ImportsOf(node *ast.File) map[string]string {
+	out := map[string]string{}
+	for _, spec := range node.Imports {
+		value, err := strconv.Unquote(spec.Path.Value)
+		if err != nil {
+			continue
+		}
+		name := path.Base(value)
+		if spec.Name != nil && spec.Name.Name != "_" && spec.Name.Name != "." {
+			name = spec.Name.Name
+		}
+		out[name] = value
+		if short, _, dotted := strings.Cut(name, "."); dotted && short != "" {
+			out[short] = value
+		}
+	}
+	return out
+}
+
+func generatedName(name string) bool {
+	return strings.HasSuffix(name, ".gen.go") || strings.HasSuffix(name, "_generated.go") || strings.HasSuffix(name, ".generated.go")
+}
+
+func IsGenerated(name string, file *ast.File) bool {
+	return generatedName(name) || ast.IsGenerated(file)
+}
+
+// PackageFiles and PackageDirs use the same immutable source selection in
+// every consumer; repeated lookups reuse the AST and token positions.
+func (t *Tree) PackageFiles(dir string) []*File {
+	return t.ByDir[filepath.ToSlash(filepath.Clean(dir))]
+}
+func (t *Tree) PackageDirs(prefix string) []string {
+	prefix = filepath.ToSlash(filepath.Clean(prefix))
+	var dirs []string
+	for dir := range t.ByDir {
+		if prefix == "." || dir == prefix || strings.HasPrefix(dir, prefix+"/") {
+			dirs = append(dirs, dir)
+		}
+	}
+	sort.Strings(dirs)
+	return dirs
+}
+
+// PackageIndex also serves small standalone readers and tests. Extractors
+// should pass their request-scoped index to reuse parsing across passes.
+func PackageIndex(root, dir string, indexes ...*Tree) (*Tree, error) {
+	if len(indexes) > 0 && indexes[0] != nil {
+		return indexes[0], nil
+	}
+	return ReadWithOptions(root, ReadOptions{IncludeGenerated: true, AllowPartial: true})
+}

package/internal/goscan/types.go

@@ -0,0 +1,99 @@
+package goscan
+
+import (
+	"bytes"
+	"go/ast"
+	"go/printer"
+	"reflect"
+	"strconv"
+	"strings"
+)
+
+// Unwrap takes the parentheses, the address-of and the pointer off an
+// expression, down to the thing itself.
+func Unwrap(expr ast.Expr) ast.Expr {
+	for {
+		switch value := expr.(type) {
+		case *ast.ParenExpr:
+			expr = value.X
+		case *ast.UnaryExpr:
+			expr = value.X
+		case *ast.StarExpr:
+			expr = value.X
+		default:
+			return expr
+		}
+	}
+}
+
+// TypeKey names a type the way the tree indexes types: "<import path>.<Name>"
+// for a named type, whether written bare or through an import; the builtin's
+// own name; "[]T" and "map[K]V" over their parts; "interface" for any
+// interface literal. Empty for a type this reader does not name.
+func (t *Tree) TypeKey(expr ast.Expr, file *File) string {
+	if expr == nil {
+		return ""
+	}
+	switch value := Unwrap(expr).(type) {
+	case *ast.Ident:
+		if IsBuiltin(value.Name) {
+			return value.Name
+		}
+		return file.Pkg + "." + value.Name
+	case *ast.SelectorExpr:
+		if base, ok := value.X.(*ast.Ident); ok {
+			return file.Imports[base.Name] + "." + value.Sel.Name
+		}
+	case *ast.ArrayType:
+		return "[]" + t.TypeKey(value.Elt, file)
+	case *ast.MapType:
+		return "map[" + t.TypeKey(value.Key, file) + "]" + t.TypeKey(value.Value, file)
+	case *ast.InterfaceType:
+		return "interface"
+	}
+	return ""
+}
+
+// IsBuiltin is whether a bare identifier is one of the language's own types.
+func IsBuiltin(name string) bool {
+	switch name {
+	case "string", "bool", "byte", "rune", "int", "int8", "int16", "int32", "int64", "uint", "uint8", "uint16", "uint32", "uint64", "float32", "float64", "error", "any":
+		return true
+	}
+	return false
+}
+
+// FieldsOf lists a struct's named fields as "name type", the name being what
+// the json tag says when it says anything, and a field tagged "-" left out:
+// the fields as they travel, not as the code calls them.
+func (t *Tree) FieldsOf(body *ast.StructType) []string {
+	var out []string
+	for _, field := range body.Fields.List {
+		if len(field.Names) == 0 {
+			continue
+		}
+		typeName := t.PrintNode(field.Type)
+		for _, ident := range field.Names {
+			name := ident.Name
+			if field.Tag != nil {
+				tagText, _ := strconv.Unquote(field.Tag.Value)
+				jsonName := strings.Split(reflect.StructTag(tagText).Get("json"), ",")[0]
+				if jsonName == "-" {
+					continue
+				}
+				if jsonName != "" {
+					name = jsonName
+				}
+			}
+			out = append(out, name+" "+typeName)
+		}
+	}
+	return out
+}
+
+// PrintNode is a node as source text.
+func (t *Tree) PrintNode(node ast.Node) string {
+	var out bytes.Buffer
+	_ = printer.Fprint(&out, t.Fset, node)
+	return out.String()
+}

package/internal/wsdl/ids.go

@@ -0,0 +1,127 @@
+package wsdl
+
+import (
+	"path/filepath"
+	"regexp"
+	"strconv"
+	"strings"
+	"unicode"
+)
+
+var versionInSource = regexp.MustCompile(`(?i)(?:^|[_-])(\d+(?:\.\d+)+)(?:[_-]|\.wsdl$)`)
+
+// APIID is the stable prefix shared by the contract extractor and call-site
+// analyzer. WSDL has no standard version field, so the protocol is the suffix.
+func APIID(contract Contract) string {
+	name := Slug(contract.Name)
+	if name == "" {
+		name = "soap"
+	}
+	return name + ".soap"
+}
+
+// APIIDs resolves the case WSDL itself cannot: two checked-in versions may
+// repeat the same service, port and targetNamespace. Only colliding interface
+// ids receive a source-backed version suffix, so an unrelated file rename does
+// not churn stable ids.
+func APIIDs(contracts []Contract) map[string]string {
+	bases := map[string]int{}
+	for _, contract := range contracts {
+		base := APIID(contract)
+		for _, iface := range contract.Interfaces {
+			bases[InterfaceID(base, iface)]++
+		}
+	}
+	out := map[string]string{}
+	for index, contract := range contracts {
+		base := APIID(contract)
+		collides := false
+		for _, iface := range contract.Interfaces {
+			if bases[InterfaceID(base, iface)] > 1 {
+				collides = true
+				break
+			}
+		}
+		if collides {
+			version := sourceVersion(contract.Source)
+			if version == "" {
+				version = Slug(strings.TrimSuffix(filepath.Base(contract.Source), filepath.Ext(contract.Source)))
+			}
+			if version == "" {
+				version = "copy-" + strconv.Itoa(index+1)
+			}
+			base += ".v" + strings.ReplaceAll(strings.TrimPrefix(version, "v"), ".", "-")
+		}
+		out[ContractKey(contract)] = base
+	}
+	return out
+}
+
+func ContractKey(contract Contract) string {
+	return contract.Source + "\x00" + contract.Name
+}
+
+func sourceVersion(source string) string {
+	match := versionInSource.FindStringSubmatch(filepath.Base(source))
+	if len(match) > 1 {
+		return match[1]
+	}
+	return ""
+}
+
+// InterfaceID keeps distinct WSDL ports distinct. A document commonly exposes
+// SOAP 1.1 and 1.2 ports with the same operations but different bindings.
+func InterfaceID(api string, iface Interface) string {
+	name := title(iface.Name)
+	if name == "" {
+		name = title(iface.PortType)
+	}
+	if name == "" {
+		return api
+	}
+	return api + "." + name
+}
+
+func CallID(api string, iface Interface, operation Operation) string {
+	return InterfaceID(api, iface) + "/" + operation.Name
+}
+
+func ExternalID(contract Contract) string {
+	id := Slug(contract.Name)
+	id = strings.TrimSuffix(id, "-service")
+	id = strings.TrimSuffix(id, "service")
+	id = strings.TrimSuffix(id, "-soap")
+	if id == "" {
+		return "soap-peer"
+	}
+	return id
+}
+
+func Slug(value string) string {
+	var out strings.Builder
+	dash := false
+	for _, r := range strings.ToLower(strings.TrimSpace(value)) {
+		if unicode.IsLetter(r) || unicode.IsDigit(r) {
+			out.WriteRune(r)
+			dash = false
+		} else if out.Len() > 0 && !dash {
+			out.WriteByte('-')
+			dash = true
+		}
+	}
+	return strings.Trim(out.String(), "-")
+}
+
+func title(value string) string {
+	var out strings.Builder
+	for _, word := range strings.FieldsFunc(value, func(r rune) bool {
+		return r == '-' || r == '_' || unicode.IsSpace(r)
+	}) {
+		runes := []rune(word)
+		if len(runes) > 0 {
+			runes[0] = unicode.ToUpper(runes[0])
+			out.WriteString(string(runes))
+		}
+	}
+	return out.String()
+}

package/internal/wsdl/ids_test.go

@@ -0,0 +1,21 @@
+package wsdl
+
+import "testing"
+
+func TestAPIIDsOnlyVersionCollidingContracts(t *testing.T) {
+	contracts := []Contract{
+		{Name: "BookingService", Source: "booking_1.0_4.0.wsdl", Interfaces: []Interface{{Name: "BookingPort"}}},
+		{Name: "BookingService", Source: "booking_1.2_4.0.wsdl", Interfaces: []Interface{{Name: "BookingPort"}}},
+		{Name: "StatusService", Source: "status.wsdl", Interfaces: []Interface{{Name: "StatusPort"}}},
+	}
+	ids := APIIDs(contracts)
+	if got := ids[ContractKey(contracts[0])]; got != "bookingservice.soap.v1-0" {
+		t.Fatalf("v1 id = %q", got)
+	}
+	if got := ids[ContractKey(contracts[1])]; got != "bookingservice.soap.v1-2" {
+		t.Fatalf("v1.2 id = %q", got)
+	}
+	if got := ids[ContractKey(contracts[2])]; got != "statusservice.soap" {
+		t.Fatalf("unrelated id = %q", got)
+	}
+}

package/internal/wsdl/model.go

@@ -0,0 +1,70 @@
+// Package wsdl reads local WSDL 1.1 contracts and the XML Schemas they reach.
+//
+// It deliberately performs no network access. A remote import is evidence that
+// part of a contract is unavailable in the checkout, and is returned as a
+// warning rather than fetched behind the caller's back.
+package wsdl
+
+// Contract is one WSDL service, or one standalone port type when the document
+// does not declare a service.
+type Contract struct {
+	Name       string
+	Namespace  string
+	Summary    string
+	Source     string
+	Interfaces []Interface
+}
+
+// Interface is a WSDL port bound to one SOAP binding. Keeping the port rather
+// than flattening the whole document preserves distinct endpoints and SOAP
+// versions when a service publishes more than one.
+type Interface struct {
+	Name       string
+	Binding    string
+	PortType   string
+	Endpoint   string
+	Version    string
+	Style      string
+	Operations []Operation
+	Messages   []Message
+}
+
+// Operation joins the abstract portType operation to its concrete SOAP
+// binding. Request, response and faults name entries in Interface.Messages.
+type Operation struct {
+	Name     string
+	Action   string
+	Doc      string
+	Request  string
+	Response string
+	Faults   []string
+	Headers  []string
+}
+
+// Message is a WSDL message or an XSD complex type reachable from one.
+type Message struct {
+	Name   string
+	Fields []Field
+}
+
+// Field is the compact XML shape the catalog can display.
+type Field struct {
+	Name string
+	Type string
+	Doc  string
+}
+
+// Result is deterministic: contracts, interfaces, operations and messages are
+// sorted by the parser before they leave the package.
+type Result struct {
+	Contracts []Contract
+	// Warnings are what stopped a document from being read in full: a remote
+	// import, a port whose binding is not here. They matter to anyone reading
+	// the contracts, including a client extractor resolving calls against them.
+	Warnings []string
+	// SchemaWarnings are about the quality of the schemas themselves, such as
+	// one name declared twice in a namespace. Nothing failed to resolve; the
+	// loader kept the first and says so. They belong to whoever publishes the
+	// contracts, not to every extractor that happens to read them.
+	SchemaWarnings []string
+}