test(kernel): add universal navigator tests (#62)

builders.go

@@ -1,7 +1,6 @@
 package tv
 
 import (
-	"github.com/snivilised/traverse/core"
 	"github.com/snivilised/traverse/internal/kernel"
 	"github.com/snivilised/traverse/internal/types"
 	"github.com/snivilised/traverse/measure"
@@ -10,7 +9,7 @@ import (
 
 type buildArtefacts struct {
 	o       *pref.Options
-	nav     core.Navigator
+	nav     types.KernelController
 	plugins []types.Plugin
 	ext     extent
 }
@@ -77,7 +76,7 @@ func (bs *Builders) buildAll() (*buildArtefacts, error) {
 		if bindErr := p.Init(); bindErr != nil {
 			return &buildArtefacts{
 				o:       o,
-				nav:     artefacts.Navigator,
+				nav:     artefacts.Controller,
 				plugins: plugins,
 				ext:     ext,
 			}, bindErr
@@ -86,7 +85,7 @@ func (bs *Builders) buildAll() (*buildArtefacts, error) {
 
 	return &buildArtefacts{
 		o:       o,
-		nav:     artefacts.Navigator,
+		nav:     artefacts.Controller,
 		plugins: plugins,
 		ext:     ext,
 	}, nil

director-resume_test.go

@@ -88,7 +88,7 @@ var _ = Describe("Director(Resume)", Ordered, func() {
 	Context("features", func() {
 		Context("Run", func() {
 			When("filter", func() {
-				It("🧪 should: register ok", func(specCtx SpecContext) {
+				FIt("🧪 should: register ok", func(specCtx SpecContext) {
 					defer leaktest.Check(GinkgoT())()
 
 					ctx, cancel := context.WithCancel(specCtx)

driver.go

@@ -22,7 +22,7 @@ func (d *driver) init() {
 			_ = m.Data
 			// now invoke session.finish
 		},
-		Matcher: services.TopicTraverseResult,
+		Matcher: services.TopicNavigationComplete,
 	})
 }
 

extent.go

@@ -16,6 +16,7 @@ type extent interface {
 	options(...pref.Option) (*pref.Options, error)
 	navFS() fs.FS
 	resFS() fs.FS
+	complete() bool
 }
 
 type fileSystems struct {
@@ -56,6 +57,10 @@ func (ex *primeExtent) options(settings ...pref.Option) (*pref.Options, error) {
 	return pref.Get(settings...)
 }
 
+func (ex *primeExtent) complete() bool {
+	return true
+}
+
 type resumeExtent struct {
 	baseExtent
 	w      *pref.Was
@@ -88,3 +93,10 @@ func (ex *resumeExtent) options(settings ...pref.Option) (*pref.Options, error)
 	//
 	return loaded.O, err
 }
+
+func (ex *resumeExtent) complete() bool {
+	// "NOT-IMPL: resumeExtent.complete -> the strategy knows this"
+	// ===> send to plugin?
+	//
+	return true
+}

internal/kernel/builder.go

@@ -1,14 +1,13 @@
 package kernel
 
 import (
-	"github.com/snivilised/traverse/core"
 	"github.com/snivilised/traverse/internal/types"
 	"github.com/snivilised/traverse/pref"
 )
 
 type (
 	Artefacts struct {
-		Navigator  core.Navigator
+		Controller types.KernelController
 		Mediator   types.Mediator
 		Facilities types.Facilities
 		Resources  *types.Resources

internal/kernel/guardian.go

@@ -16,17 +16,21 @@ type (
 	invocationIt    = collections.Iterator[types.Link]
 )
 
+type owned struct {
+	mums measure.Mutables
+}
+
 // anchor is a specialised link that should always be the
 // last in the chain and contains the original client's handler.
 type anchor struct {
 	target core.Client
-	mums   measure.Mutables
+	owned  owned
 }
 
 func (t *anchor) Next(node *core.Node) (bool, error) {
 	if metric := lo.Ternary(node.IsFolder(),
-		t.mums[enums.MetricNoFoldersInvoked],
-		t.mums[enums.MetricNoFilesInvoked],
+		t.owned.mums[enums.MetricNoFoldersInvoked],
+		t.owned.mums[enums.MetricNoFilesInvoked],
 	); metric != nil {
 		metric.Tick()
 	}
@@ -67,7 +71,9 @@ func newGuardian(callback core.Client,
 	stack := collections.NewStack[types.Link]()
 	stack.Push(&anchor{
 		target: callback,
-		mums:   mums,
+		owned: owned{
+			mums: mums,
+		},
 	})
 
 	return &guardian{

internal/kernel/kernel-defs.go

@@ -12,6 +12,8 @@ import (
 type (
 	// NavigatorImpl
 	NavigatorImpl interface {
+		Starting(session types.Session)
+
 		// Top
 		Top(ctx context.Context,
 			ns *navigationStatic,
@@ -24,6 +26,8 @@ type (
 			ns *navigationStatic,
 			current *core.Node,
 		) (bool, error)
+
+		Result(ctx context.Context, err error) *types.KernelResult
 	}
 
 	// NavigatorDriver

internal/kernel/kernel-support_test.go

@@ -1,6 +1,70 @@
 package kernel_test
 
+import (
+	"io/fs"
+
+	. "github.com/onsi/ginkgo/v2" //nolint:revive // ok
+	. "github.com/onsi/gomega"    //nolint:revive // ok
+	"github.com/snivilised/traverse/core"
+	"github.com/snivilised/traverse/cycle"
+	"github.com/snivilised/traverse/enums"
+	"github.com/snivilised/traverse/internal/helpers"
+)
+
 const (
 	RootPath    = "traversal-root-path"
 	RestorePath = "/from-restore-path"
 )
+
+type recordingMap map[string]int
+type recordingScopeMap map[string]enums.FilterScope
+type recordingOrderMap map[string]int
+
+type directoryQuantities struct {
+	files    uint
+	folders  uint
+	children map[string]int
+}
+
+type naviTE struct {
+	message       string
+	should        string
+	relative      string
+	once          bool
+	visit         bool
+	caseSensitive bool
+	subscription  enums.Subscription
+	callback      core.Client
+	mandatory     []string
+	prohibited    []string
+	expectedNoOf  directoryQuantities
+}
+
+func begin(em string) cycle.BeginHandler {
+	return func(root string) {
+		GinkgoWriter.Printf(
+			"---> %v [traverse-navigator-test:BEGIN], root: '%v'\n", em, root,
+		)
+	}
+}
+
+func universalCallback(name string) core.Client {
+	return func(node *core.Node) error {
+		depth := node.Extension.Depth
+		GinkgoWriter.Printf(
+			"---> 🌊 UNIVERSAL//%v-CALLBACK: (depth:%v) '%v'\n", name, depth, node.Path,
+		)
+		Expect(node.Extension).NotTo(BeNil(), helpers.Reason(node.Path))
+		return nil
+	}
+}
+
+func subscribes(subscription enums.Subscription, de fs.DirEntry) bool {
+	isAnySubscription := (subscription == enums.SubscribeUniversal)
+
+	files := (subscription == enums.SubscribeFiles) && (!de.IsDir())
+	folders := ((subscription == enums.SubscribeFolders) ||
+		subscription == enums.SubscribeFoldersWithFiles) && (de.IsDir())
+
+	return isAnySubscription || files || folders
+}

internal/kernel/mediator.go

@@ -13,10 +13,6 @@ import (
 
 // mediator controls traversal events, sends notifications and emits life-cycle events
 
-type owned struct {
-	mums measure.Mutables
-}
-
 type mediator struct {
 	root      string
 	impl      NavigatorImpl
@@ -25,7 +21,6 @@ type mediator struct {
 	pad       *scratchPad // gets created just before nav begins
 	o         *pref.Options
 	resources *types.Resources
-	owned     owned
 	// there should be a registration phase; but doing so mean that
 	// these entities should already exist, which is counter productive.
 	// possibly use dependency inject where entities declare their
@@ -48,24 +43,19 @@ func newMediator(using *pref.Using,
 	sealer types.GuardianSealer,
 	res *types.Resources,
 ) *mediator {
-	mums := res.Supervisor.Many(
-		enums.MetricNoFilesInvoked,
-		enums.MetricNoFoldersInvoked,
-	)
-
 	return &mediator{
-		root:   using.Root,
-		impl:   impl,
-		client: newGuardian(using.Handler, sealer, mums),
+		root: using.Root,
+		impl: impl,
+		client: newGuardian(using.Handler, sealer, res.Supervisor.Many(
+			enums.MetricNoFilesInvoked,
+			enums.MetricNoFoldersInvoked,
+		)),
 		frame: &navigationFrame{
 			periscope: level.New(),
 		},
 		pad:       newScratch(o),
 		o:         o,
 		resources: res,
-		owned: owned{
-			mums: mums,
-		},
 	}
 }
 
@@ -77,6 +67,10 @@ func (m *mediator) Unwind(role enums.Role) error {
 	return m.client.Unwind(role)
 }
 
+func (m *mediator) Starting(session types.Session) {
+	m.impl.Starting(session)
+}
+
 func (m *mediator) Navigate(ctx context.Context) (core.TraverseResult, error) {
 	// could we pass in the invokable client to Top so the navigators can invoke
 	// as required.

internal/kernel/navigation-controller.go

@@ -8,15 +8,23 @@ import (
 )
 
 type NavigationController struct {
-	mediator *mediator
+	Mediator *mediator
+}
+
+func (nc *NavigationController) Result(ctx context.Context, err error) *types.KernelResult {
+	return nc.Mediator.impl.Result(ctx, err)
+}
+
+func (nc *NavigationController) Starting(session types.Session) {
+	nc.Mediator.Starting(session)
 }
 
 func (nc *NavigationController) Navigate(ctx context.Context) (core.TraverseResult, error) {
-	return nc.mediator.Navigate(ctx)
+	return nc.Mediator.Navigate(ctx)
 }
 
 func (nc *NavigationController) Impl() NavigatorImpl {
-	return nc.mediator.impl
+	return nc.Mediator.impl
 }
 
 func (nc *NavigationController) Register(types.Plugin) error {

internal/kernel/navigator-agent.go

@@ -46,9 +46,7 @@ func top(ctx context.Context,
 		},
 	)
 
-	return &types.KernelResult{
-		Err: err,
-	}, nil
+	return ns.mediator.impl.Result(ctx, err), err
 }
 
 const (

internal/kernel/navigator-factory.go

@@ -19,9 +19,9 @@ func New(using *pref.Using, o *pref.Options,
 	controller := newController(using, o, impl, sealer, res)
 
 	return &Artefacts{
-		Navigator: controller,
-		Mediator:  controller.mediator,
-		Resources: res,
+		Controller: controller,
+		Mediator:   controller.Mediator,
+		Resources:  res,
 	}
 }
 
@@ -32,7 +32,7 @@ func newController(using *pref.Using,
 	res *types.Resources,
 ) *NavigationController {
 	return &NavigationController{
-		mediator: newMediator(using, o, impl, sealer, res),
+		Mediator: newMediator(using, o, impl, sealer, res),
 	}
 }
 

internal/kernel/navigator-hades.go

@@ -4,10 +4,11 @@ import (
 	"context"
 
 	"github.com/snivilised/traverse/core"
+	"github.com/snivilised/traverse/internal/types"
 	"github.com/snivilised/traverse/measure"
 )
 
-func HadesNav(err error) core.Navigator {
+func HadesNav(err error) types.KernelController {
 	return &navigatorHades{
 		err: err,
 	}
@@ -29,6 +30,15 @@ type navigatorHades struct {
 	err error
 }
 
+func (n *navigatorHades) Result(_ context.Context, err error) *types.KernelResult {
+	return &types.KernelResult{
+		Err: err,
+	}
+}
+
+func (n *navigatorHades) Starting(types.Session) {
+}
+
 func (n *navigatorHades) Navigate(_ context.Context) (core.TraverseResult, error) {
 	return &hadesResult{
 		err: n.err,