feat: added support for the Arazzo specification

Author: TristanSpeakEasy

README.md

@@ -0,0 +1,9 @@
+# github.com/speakeasy-api/openapi
+
+The Speakeasy OpenAPI module provides a set of packages and tools for working with OpenAPI Specification documents.
+
+## Main Packages
+
+### [arazzo](./arazzo/README.md)
+
+The `arazzo` package provides an API for working with Arazzo documents including reading, creating, mutating, walking and validating them.

arazzo/README.md

@@ -0,0 +1,184 @@
+# github.com/speakeasy-api/openapi/arazzo
+
+The Arazzo package provides an API for working with Arazzo documents including reading, creating, mutating, walking and validating them.
+
+For more details on the Arazzo specification see [Speakeasy's Arazzo Documentation](https://www.speakeasy.com/openapi/arazzo).
+
+For details on the API available via the `arazzo` package see [https://pkg.go.dev/github.com/speakeasy-api/openapi/arazzo](https://pkg.go.dev/github.com/speakeasy-api/openapi/arazzo).
+
+## Reading
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ "os"
+
+ "github.com/speakeasy-api/openapi/arazzo"
+)
+
+func main() {
+ ctx := context.Background()
+
+ data, err := os.ReadFile("arazzo.yaml")
+ if err != nil {
+  panic(err)
+ }
+
+ arazzo, validationErrs, err := arazzo.Unmarshal(ctx, data, "arazzo.yaml")
+ if err != nil {
+  panic(err)
+ }
+
+ fmt.Printf("%+v\n", arazzo)
+ fmt.Printf("%+v\n", validationErrs)
+}
+```
+
+## Creating
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/speakeasy-api/openapi/arazzo"
+)
+
+func main() {
+ ctx := context.Background()
+
+ arazzo := &arazzo.Arazzo{
+  Arazzo: Version,
+  Info: arazzo.Info{
+   Title:   "My Workflow",
+   Summary: arazzo.pointer.From("A summary"),
+   Version: "1.0.0",
+  },
+  // ...
+ }
+
+ buf := bytes.NewBuffer([]byte{})
+
+ err := arazzo.Marshal(ctx, buf)
+ if err != nil {
+  panic(err)
+ }
+
+ fmt.Printf("%s", buf.String())
+}
+```
+
+## Mutating
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+
+ "github.com/speakeasy-api/openapi/arazzo"
+)
+
+func main() {
+ ctx := context.Background()
+
+ data, err := os.ReadFile("arazzo.yaml")
+ if err != nil {
+  panic(err)
+ }
+
+ arazzo, _, err := arazzo.Unmarshal(ctx, data, "arazzo.yaml")
+ if err != nil {
+  panic(err)
+ }
+ 
+ arazzo.Info.Title = "My updated workflow title"
+
+ buf := bytes.NewBuffer([]byte{})
+
+ err := arazzo.Marshal(ctx, buf)
+ if err != nil {
+  panic(err)
+ }
+
+ fmt.Printf("%s", buf.String())
+}
+```
+
+## Walking
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ "os"
+
+ "github.com/speakeasy-api/openapi/arazzo"
+)
+
+func main() {
+ ctx := context.Background()
+
+ data, err := os.ReadFile("arazzo.yaml")
+ if err != nil {
+  panic(err)
+ }
+
+ arazzo, _, err := arazzo.Unmarshal(ctx, data, "arazzo.yaml")
+ if err != nil {
+  panic(err)
+ }
+
+ err = arazzo.Walk(ctx, func(ctx context.Context, node, parent arazzo.MatchFunc, arazzo *arazzo.Arazzo) error {
+  return node(arazzo.Matcher{
+   Workflow: func(workflow *arazzo.Workflow) error {
+    fmt.Printf("Workflow: %s\n", workflow.WorkflowID)
+    return nil
+   },
+  })
+ })
+ if err != nil {
+  panic(err)
+ }
+}
+```
+
+## Validating
+
+```go
+package main
+
+import (
+ "context"
+ "fmt"
+ "os"
+
+ "github.com/speakeasy-api/openapi/arazzo"
+)
+
+func main() {
+ ctx := context.Background()
+
+ data, err := os.ReadFile("arazzo.yaml")
+ if err != nil {
+  panic(err)
+ }
+
+ arazzo, validationErrs, err := arazzo.Unmarshal(ctx, data, "arazzo.yaml")
+ if err != nil {
+  panic(err)
+ }
+ 
+ for _, err := range validationErrs {
+  fmt.Printf("%s\n", err.Error())
+ }
+}
+```

arazzo/arazzo.go

@@ -0,0 +1,188 @@
+// package arazzo provides an API for working with Arazzo documents including reading, creating, mutating, walking and validating them.
+//
+// The Arazzo Specification is a mechanism for orchestrating API calls, defining their sequences and dependencies, to achieve specific outcomes when working with API descriptions like OpenAPI.
+package arazzo
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"io"
+	"slices"
+
+	"github.com/speakeasy-api/openapi/arazzo/core"
+	"github.com/speakeasy-api/openapi/extensions"
+	"github.com/speakeasy-api/openapi/marshaller"
+	"github.com/speakeasy-api/openapi/validation"
+	"github.com/speakeasy-api/openapi/yml"
+)
+
+// Version is the version of the Arazzo Specification that this package conforms to.
+const Version = "1.0.0"
+
+// Arazzo is the root object for an Arazzo document.
+type Arazzo struct {
+	// Arazzo is the version of the Arazzo Specification that this document conforms to.
+	Arazzo string
+	// Info provides metadata about the Arazzo document.
+	Info Info
+	// SourceDescriptions provides a list of SourceDescription objects that describe the source of the data that the workflow is orchestrating.
+	SourceDescriptions SourceDescriptions
+	// Workflows provides a list of Workflow objects that describe the orchestration of API calls.
+	Workflows Workflows
+	// Components provides a list of reusable components that can be used in the workflow.
+	Components *Components
+	// Extensions provides a list of extensions to the Arazzo document.
+	Extensions *extensions.Extensions
+
+	core core.Arazzo
+}
+
+var _ model[core.Arazzo] = (*Arazzo)(nil)
+
+type Option[T any] func(o *T)
+
+type unmarshalOptions struct {
+	skipValidation bool
+}
+
+// WithSkipValidation will skip validation of the Arazzo document during unmarshalling.
+// Useful to quickly load a document that will be mutated and validated later.
+func WithSkipValidation() Option[unmarshalOptions] {
+	return func(o *unmarshalOptions) {
+		o.skipValidation = true
+	}
+}
+
+// Unmarshal will unmarshal and validate an Arazzo document from the provided io.Reader.
+// Validation can be skipped by using arazzo.WithSkipValidation() as one of the options when calling this function.
+func Unmarshal(ctx context.Context, doc io.Reader, opts ...Option[unmarshalOptions]) (*Arazzo, []error, error) {
+	o := unmarshalOptions{}
+	for _, opt := range opts {
+		opt(&o)
+	}
+
+	ctx = validation.ContextWithValidationContext(ctx)
+
+	c, err := core.Unmarshal(ctx, doc)
+	if err != nil {
+		return nil, nil, err
+	}
+
+	arazzo := &Arazzo{}
+	if err := marshaller.PopulateModel(*c, arazzo); err != nil {
+		return nil, nil, err
+	}
+	arazzo.core = *c
+
+	var validationErrs []error
+	if !o.skipValidation {
+		validationErrs = validation.GetValidationErrors(ctx)
+		validationErrs = append(validationErrs, arazzo.Validate(ctx)...)
+		slices.SortFunc(validationErrs, func(a, b error) int {
+			var aValidationErr *validation.Error
+			var bValidationErr *validation.Error
+			aIsValidationErr := errors.As(a, &aValidationErr)
+			bIsValidationErr := errors.As(b, &bValidationErr)
+			if aIsValidationErr && bIsValidationErr {
+				if aValidationErr.Line == bValidationErr.Line {
+					return aValidationErr.Column - bValidationErr.Column
+				}
+				return aValidationErr.Line - bValidationErr.Line
+			} else if aIsValidationErr {
+				return -1
+			} else if bIsValidationErr {
+				return 1
+			}
+
+			return 0
+		})
+	}
+
+	return arazzo, validationErrs, nil
+}
+
+// Marshal will marshal the provided Arazzo document to the provided io.Writer.
+func Marshal(ctx context.Context, arazzo *Arazzo, w io.Writer) error {
+	if arazzo == nil {
+		return errors.New("nil *Arazzo")
+	}
+
+	if err := arazzo.Marshal(ctx, w); err != nil {
+		return err
+	}
+
+	return nil
+}
+
+// GetCore will return the low level representation of the Arazzo document.
+// Useful for accessing line and column numbers for various nodes in the backing yaml/json document.
+func (a *Arazzo) GetCore() *core.Arazzo {
+	return &a.core
+}
+
+// Marshal will marshal the Arazzo document to the provided io.Writer.
+func (a *Arazzo) Marshal(ctx context.Context, w io.Writer) error {
+	ctx = yml.ContextWithConfig(ctx, a.core.Config)
+
+	if _, err := marshaller.SyncValue(ctx, a, &a.core, nil); err != nil {
+		return err
+	}
+
+	return a.core.Marshal(ctx, w)
+}
+
+// Validate will validate the Arazzo document against the Arazzo Specification.
+func (a *Arazzo) Validate(ctx context.Context, opts ...validation.Option) []error {
+	opts = append(opts, validation.WithContextObject(a))
+
+	errs := []error{}
+
+	if a.Arazzo != Version {
+		errs = append(errs, &validation.Error{
+			Message: "Arazzo version must be 1.0.0",
+			Line:    a.core.Arazzo.GetValueNodeOrRoot(a.core.RootNode).Line,
+			Column:  a.core.Arazzo.GetValueNodeOrRoot(a.core.RootNode).Column,
+		})
+	}
+
+	errs = append(errs, a.Info.Validate(ctx, opts...)...)
+
+	sourceDescriptionNames := make(map[string]bool)
+
+	for i, sourceDescription := range a.SourceDescriptions {
+		errs = append(errs, sourceDescription.Validate(ctx, opts...)...)
+
+		if _, ok := sourceDescriptionNames[sourceDescription.Name]; ok {
+			errs = append(errs, &validation.Error{
+				Message: fmt.Sprintf("sourceDescription name %s is not unique", sourceDescription.Name),
+				Line:    a.core.SourceDescriptions.GetSliceValueNodeOrRoot(i, a.core.RootNode).Line,
+				Column:  a.core.SourceDescriptions.GetSliceValueNodeOrRoot(i, a.core.RootNode).Column,
+			})
+		}
+
+		sourceDescriptionNames[sourceDescription.Name] = true
+	}
+
+	workflowIds := make(map[string]bool)
+
+	for i, workflow := range a.Workflows {
+		errs = append(errs, workflow.Validate(ctx, opts...)...)
+
+		if _, ok := workflowIds[workflow.WorkflowID]; ok {
+			errs = append(errs, &validation.Error{
+				Message: fmt.Sprintf("workflowId %s is not unique", workflow.WorkflowID),
+				Line:    a.core.Workflows.GetSliceValueNodeOrRoot(i, a.core.RootNode).Line,
+				Column:  a.core.Workflows.GetSliceValueNodeOrRoot(i, a.core.RootNode).Column,
+			})
+		}
+
+		workflowIds[workflow.WorkflowID] = true
+	}
+
+	if a.Components != nil {
+		errs = append(errs, a.Components.Validate(ctx, opts...)...)
+	}
+
+	return errs
+}