feat: formalise bootstrap phases (#29)

builders.go

@@ -0,0 +1,56 @@
+package traverse
+
+import (
+	"errors"
+
+	"github.com/snivilised/traverse/core"
+	"github.com/snivilised/traverse/internal/types"
+	"github.com/snivilised/traverse/pref"
+)
+
+type buildArtefacts struct {
+	o       *pref.Options
+	nav     core.Navigator
+	plugins []types.Plugin
+}
+
+type Builders struct {
+	ob optionsBuilder
+	nb navigatorBuilder
+	pb pluginsBuilder
+}
+
+func (bs *Builders) buildAll() (*buildArtefacts, error) {
+	o, optionsErr := bs.ob.build()
+	if optionsErr != nil {
+		return nil, optionsErr
+	}
+
+	nav, navErr := bs.nb.build(o)
+	if navErr != nil {
+		return nil, navErr
+	}
+
+	plugins, pluginsErr := bs.pb.build(o)
+	if pluginsErr != nil {
+		return nil, pluginsErr
+	}
+
+	if host, ok := nav.(types.UsePlugin); ok {
+		es := []error{}
+		for _, p := range plugins {
+			registrationErr := host.Register(p)
+			es = append(es, registrationErr)
+		}
+
+		if pluginErr := errors.Join(es...); pluginErr != nil {
+			return nil, pluginErr
+		}
+	}
+
+	return &buildArtefacts{
+		o:       o,
+		nav:     nav,
+		plugins: plugins,
+	}, nil
+}

core/core-defs.go

@@ -1,5 +1,7 @@
 package core
 
+import "github.com/snivilised/traverse/enums"
+
 // core contains universal definitions and handles cross cutting concerns
 // try to keep to a minimum to reduce rippling changes
 
@@ -33,3 +35,53 @@ type (
 	// the traversal node, such as directory ascend or descend.
 	NodeHandler func(node *Node)
 )
+
+type Using struct {
+	Root         string
+	Subscription enums.Subscription
+	Handler      Client
+}
+
+func (u Using) Validate() error {
+	if u.Root == "" {
+		return UsingError{
+			message: "missing root path",
+		}
+	}
+
+	if u.Subscription == enums.SubscribeUndefined {
+		return UsingError{
+			message: "missing subscription",
+		}
+	}
+
+	if u.Handler == nil {
+		return UsingError{
+			message: "missing handler",
+		}
+	}
+
+	return nil
+}
+
+type As struct {
+	Using
+	From     string
+	Strategy enums.ResumeStrategy
+}
+
+func (a As) Validate() error {
+	if a.From == "" {
+		return UsingError{
+			message: "missing restore from path",
+		}
+	}
+
+	if a.Strategy == enums.ResumeStrategyUndefined {
+		return UsingError{
+			message: "missing subscription",
+		}
+	}
+
+	return a.Using.Validate()
+}

core/errors.go

@@ -0,0 +1,14 @@
+package core
+
+import (
+	"fmt"
+)
+
+type UsingError struct {
+	message string
+}
+
+func (e UsingError) Error() string {
+	// TODO: i18n
+	return fmt.Sprintf("using error: %v", e.message)
+}

core/filtering.go

@@ -0,0 +1,4 @@
+package core
+
+type FilterDef struct {
+}

cycle/events.go

@@ -5,11 +5,11 @@ import (
 )
 
 type (
-	broadcasterFunc[F any] func(listeners []F) F
+	announce[F any] func(listeners []F) F
 
 	Dispatch[F any] struct {
 		Invoke      F
-		broadcaster broadcasterFunc[F]
+		broadcaster announce[F]
 	}
 
 	// NotificationCtrl contains the handler function to be invoked. The control

director-error_test.go

@@ -0,0 +1,97 @@
+package traverse_test
+
+import (
+	"fmt"
+
+	. "github.com/onsi/ginkgo/v2" //nolint:revive // ok
+	. "github.com/onsi/gomega"    //nolint:revive // ok
+
+	"github.com/snivilised/traverse"
+	"github.com/snivilised/traverse/internal/services"
+)
+
+type traverseErrorTE struct {
+	given string
+	using *traverse.Using
+	as    *traverse.As
+}
+
+var _ = Describe("director error", Ordered, func() {
+	var handler traverse.Client
+
+	BeforeAll(func() {
+		handler = func(_ *traverse.Node) error {
+			return nil
+		}
+	})
+
+	BeforeEach(func() {
+		services.Reset()
+	})
+
+	DescribeTable("Validate",
+		func(entry *traverseErrorTE) {
+			if entry.using != nil {
+				Expect(entry.using.Validate()).NotTo(Succeed())
+
+				return
+			}
+
+			if entry.as != nil {
+				Expect(entry.as.Validate()).NotTo(Succeed())
+
+				return
+			}
+		},
+		func(entry *traverseErrorTE) string {
+			return fmt.Sprintf("given: %v, 🧪 should fail", entry.given)
+		},
+		Entry(nil, &traverseErrorTE{
+			given: "using missing root path",
+			using: &traverse.Using{
+				Subscription: traverse.SubscribeFiles,
+				Handler:      handler,
+			},
+		}),
+
+		Entry(nil, &traverseErrorTE{
+			given: "using missing subscription",
+			using: &traverse.Using{
+				Root:    "/root-traverse-path",
+				Handler: handler,
+			},
+		}),
+
+		Entry(nil, &traverseErrorTE{
+			given: "using missing handler",
+			using: &traverse.Using{
+				Root:         "/root-traverse-path",
+				Subscription: traverse.SubscribeFiles,
+			},
+		}),
+
+		Entry(nil, &traverseErrorTE{
+			given: "as missing restore from path",
+			as: &traverse.As{
+				Using: traverse.Using{
+					Root:         "/root-traverse-path",
+					Subscription: traverse.SubscribeFiles,
+					Handler:      handler,
+				},
+				Strategy: traverse.ResumeStrategySpawn,
+			},
+		}),
+
+		Entry(nil, &traverseErrorTE{
+			given: "as missing resume strategy",
+			as: &traverse.As{
+				Using: traverse.Using{
+					Root:         "/root-traverse-path",
+					Subscription: traverse.SubscribeFiles,
+					Handler:      handler,
+				},
+				From: "/restore-from-path",
+			},
+		}),
+	)
+})