feat(kernel): announce kernel result (#62)

.vscode/settings.json

@@ -49,6 +49,7 @@
     "icase",
     "ineffassign",
     "jibberjabber",
+    "Kontroller",
     "leaktest",
     "linecomment",
     "linters",

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
+	kc      types.KernelController
 	plugins []types.Plugin
 	ext     extent
 }
@@ -34,7 +33,7 @@ func (bs *Builders) buildAll() (*buildArtefacts, error) {
 	if optionsErr != nil {
 		return &buildArtefacts{
 			o:   o,
-			nav: kernel.HadesNav(optionsErr),
+			kc:  kernel.HadesNav(optionsErr),
 			ext: ext,
 		}, optionsErr
 	}
@@ -51,7 +50,7 @@ func (bs *Builders) buildAll() (*buildArtefacts, error) {
 	if navErr != nil {
 		return &buildArtefacts{
 			o:   o,
-			nav: kernel.HadesNav(navErr),
+			kc:  kernel.HadesNav(navErr),
 			ext: ext,
 		}, navErr
 	}
@@ -60,13 +59,14 @@ func (bs *Builders) buildAll() (*buildArtefacts, error) {
 	//
 	plugins, pluginsErr := bs.plugins.build(o,
 		artefacts.Mediator,
-		ext.plugin(artefacts.Mediator),
+		artefacts.Kontroller,
+		ext.plugin(artefacts),
 	)
 
 	if pluginsErr != nil {
 		return &buildArtefacts{
 			o:   o,
-			nav: kernel.HadesNav(pluginsErr),
+			kc:  kernel.HadesNav(pluginsErr),
 			ext: ext,
 		}, pluginsErr
 	}
@@ -77,7 +77,7 @@ func (bs *Builders) buildAll() (*buildArtefacts, error) {
 		if bindErr := p.Init(); bindErr != nil {
 			return &buildArtefacts{
 				o:       o,
-				nav:     artefacts.Navigator,
+				kc:      artefacts.Kontroller,
 				plugins: plugins,
 				ext:     ext,
 			}, bindErr
@@ -86,7 +86,7 @@ func (bs *Builders) buildAll() (*buildArtefacts, error) {
 
 	return &buildArtefacts{
 		o:       o,
-		nav:     artefacts.Navigator,
+		kc:      artefacts.Kontroller,
 		plugins: plugins,
 		ext:     ext,
 	}, nil

core/core-defs.go

@@ -1,25 +1,42 @@
 package core
 
 import (
+	"time"
+
 	"github.com/snivilised/traverse/measure"
 )
 
 // core contains universal definitions and handles user facing cross
 // cutting concerns try to keep to a minimum to reduce rippling changes.
 
 type (
+	// ResultCompletion used to determine if the result really represents
+	// final navigation completion.
+	ResultCompletion interface {
+		IsComplete() bool
+	}
+
+	Completion func() bool
+
+	// Session represents a traversal session and keeps tracks of
+	// timing.
+	Session interface {
+		ResultCompletion
+		StartedAt() time.Time
+		Elapsed() time.Duration
+	}
+
 	// TraverseResult
 	TraverseResult interface {
 		Metrics() measure.Reporter
+		Session() Session
 		Error() error
 	}
 
 	// Client is the callback invoked for each file system node found
 	// during traversal.
 	Client func(node *Node) error
-)
 
-type (
 	// SimpleHandler is a function that takes no parameters and can
 	// be used by any notification with this signature.
 	SimpleHandler func()
@@ -38,3 +55,7 @@ type (
 	// the traversal node, such as directory ascend or descend.
 	NodeHandler func(node *Node)
 )
+
+func (fn Completion) IsComplete() bool {
+	return fn()
+}

cycle/event-end_test.go

@@ -5,11 +5,13 @@ import (
 	. "github.com/onsi/gomega"    //nolint:revive // ok
 
 	"github.com/snivilised/traverse/core"
+	"github.com/snivilised/traverse/internal/types"
 	"github.com/snivilised/traverse/pref"
 )
 
 var _ = Describe("event", func() {
-	var result testResult
+	var result types.KernelResult
+
 	Context("end", func() {
 		Context("single", func() {
 			When("listener", func() {

cycle/support_test.go

@@ -1,20 +1,6 @@
 package cycle_test
 
-import "github.com/snivilised/traverse/measure"
-
 const (
 	traversalRoot = "/traversal-root"
 	anotherRoot   = "/another-root"
 )
-
-type testResult struct {
-	err error
-}
-
-func (r *testResult) Metrics() measure.Reporter {
-	return nil
-}
-
-func (r *testResult) Error() error {
-	return r.err
-}

director.go

@@ -19,6 +19,7 @@ type ifActive func(o *pref.Options, mediator types.Mediator) types.Plugin
 // to activate features according to option selections. other plugins will
 // be initialised after primary plugins
 func activated(o *pref.Options, mediator types.Mediator,
+	kc types.KernelController,
 	others ...types.Plugin,
 ) (plugins []types.Plugin, err error) {
 	var (
@@ -42,7 +43,7 @@ func activated(o *pref.Options, mediator types.Mediator,
 	}
 
 	for _, plugin := range plugins {
-		err = plugin.Register()
+		err = plugin.Register(kc)
 
 		if err != nil {
 			return nil, err
@@ -88,8 +89,10 @@ func Prime(using *pref.Using, settings ...pref.Option) *Builders {
 
 			return ext.options(settings...)
 		}),
-		navigator: kernel.Builder(func(o *pref.Options, res *types.Resources) (*kernel.Artefacts, error) {
-			return kernel.New(using, o, &kernel.Benign{}, res), nil
+		navigator: kernel.Builder(func(o *pref.Options,
+			resources *types.Resources,
+		) (*kernel.Artefacts, error) {
+			return kernel.New(using, o, &kernel.Benign{}, resources), nil
 		}),
 		plugins: features(activated), // swap over features & activated
 	}
@@ -132,8 +135,10 @@ func Resume(was *Was, settings ...pref.Option) *Builders {
 
 			return ext.options(settings...)
 		}),
-		navigator: kernel.Builder(func(o *pref.Options, res *types.Resources) (*kernel.Artefacts, error) {
-			artefacts := kernel.New(&was.Using, o, resume.GetSealer(was), res)
+		navigator: kernel.Builder(func(o *pref.Options,
+			resources *types.Resources,
+		) (*kernel.Artefacts, error) {
+			artefacts := kernel.New(&was.Using, o, resume.GetSealer(was), resources)
 
 			return resume.NewController(was, artefacts), nil
 		}),

driver.go

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

extent.go

@@ -12,10 +12,11 @@ import (
 type extent interface {
 	using() *pref.Using
 	was() *pref.Was
-	plugin(types.Mediator) types.Plugin
+	plugin(*kernel.Artefacts) types.Plugin
 	options(...pref.Option) (*pref.Options, error)
 	navFS() fs.FS
 	resFS() fs.FS
+	complete() bool
 }
 
 type fileSystems struct {
@@ -48,18 +49,23 @@ func (ex *primeExtent) was() *pref.Was {
 	return nil
 }
 
-func (ex *primeExtent) plugin(types.Mediator) types.Plugin {
+func (ex *primeExtent) plugin(*kernel.Artefacts) types.Plugin {
 	return nil
 }
 
 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
 	loaded *pref.LoadInfo
+	rp     *resume.Plugin
 }
 
 func (ex *resumeExtent) using() *pref.Using {
@@ -70,12 +76,15 @@ func (ex *resumeExtent) was() *pref.Was {
 	return ex.w
 }
 
-func (ex *resumeExtent) plugin(mediator types.Mediator) types.Plugin {
-	return &resume.Plugin{
+func (ex *resumeExtent) plugin(artefacts *kernel.Artefacts) types.Plugin {
+	ex.rp = &resume.Plugin{
 		BasePlugin: kernel.BasePlugin{
-			Mediator: mediator,
+			Mediator: artefacts.Mediator,
 		},
+		IfResult: artefacts.IfResult,
 	}
+
+	return ex.rp
 }
 
 func (ex *resumeExtent) options(settings ...pref.Option) (*pref.Options, error) {
@@ -88,3 +97,7 @@ func (ex *resumeExtent) options(settings ...pref.Option) (*pref.Options, error)
 	//
 	return loaded.O, err
 }
+
+func (ex *resumeExtent) complete() bool {
+	return ex.rp.IfResult.IsComplete()
+}

factories.go

@@ -42,7 +42,7 @@ func (f *walkerFac) Configure() Director {
 			session{
 				sync: &sequential{
 					trunk: trunk{
-						nav: artefacts.nav,
+						kc:  artefacts.kc,
 						o:   artefacts.o,
 						ext: artefacts.ext,
 						err: err,
@@ -70,7 +70,7 @@ func (f *runnerFac) Configure() Director {
 			session{
 				sync: &concurrent{
 					trunk: trunk{
-						nav: artefacts.nav,
+						kc:  artefacts.kc,
 						o:   artefacts.o,
 						ext: artefacts.ext,
 						err: err,

internal-traverse-defs.go

@@ -20,13 +20,25 @@ func (fn optionals) build(ext extent) (*pref.Options, error) {
 
 // pluginsBuilder
 type pluginsBuilder interface {
-	build(*pref.Options, types.Mediator, ...types.Plugin) ([]types.Plugin, error)
+	build(o *pref.Options,
+		mediator types.Mediator,
+		kc types.KernelController,
+		others ...types.Plugin,
+	) ([]types.Plugin, error)
 }
 
-type features func(*pref.Options, types.Mediator, ...types.Plugin) ([]types.Plugin, error)
-
-func (fn features) build(o *pref.Options, mediator types.Mediator, others ...types.Plugin) ([]types.Plugin, error) {
-	return fn(o, mediator, others...)
+type features func(*pref.Options,
+	types.Mediator,
+	types.KernelController,
+	...types.Plugin,
+) ([]types.Plugin, error)
+
+func (fn features) build(o *pref.Options,
+	mediator types.Mediator,
+	kc types.KernelController,
+	others ...types.Plugin,
+) ([]types.Plugin, error) {
+	return fn(o, mediator, kc, others...)
 }
 
 type fsBuilder interface {

internal/helpers/directory-tree-builder.go

@@ -29,15 +29,19 @@ func Musico(portion string, verbose bool) (fsys fstest.MapFS, root string) {
 		},
 	}
 
-	return fsys, Provision(NewMemWriteProvider(fsys, os.ReadFile, portion), verbose)
+	return fsys, Provision(
+		NewMemWriteProvider(fsys, os.ReadFile, portion),
+		portion,
+		verbose,
+	)
 }
 
-func Provision(provider *IOProvider, verbose bool) (root string) {
+func Provision(provider *IOProvider, portion string, verbose bool) (root string) {
 	repo := Repo(filepath.Join("..", "..", "test", "data", "MUSICO"))
 	utils.Must(ensure(repo, provider, verbose))
 
 	if verbose {
-		fmt.Printf("\n🤖 re-generated tree at '%v'\n", repo)
+		fmt.Printf("\n🤖 re-generated tree at '%v' (filter: '%v')\n\n", repo, portion)
 	}
 
 	return repo
@@ -83,7 +87,10 @@ func TrimRoot(root string) string {
 }
 
 // NewMemWriteProvider
-func NewMemWriteProvider(store fstest.MapFS, indexReader readFile, portion string) *IOProvider {
+func NewMemWriteProvider(store fstest.MapFS,
+	indexReader readFile,
+	portion string,
+) *IOProvider {
 	filter := lo.Ternary(portion != "",
 		matcher(func(path string) bool {
 			return strings.Contains(path, portion)

internal/hiber/hibernate-plugin.go

@@ -28,7 +28,9 @@ func (p *Plugin) Name() string {
 	return "hibernation"
 }
 
-func (p *Plugin) Register() error {
+func (p *Plugin) Register(kc types.KernelController) error {
+	p.Kontroller = kc
+
 	return nil
 }
 

internal/kernel/base-plugin.go

@@ -5,5 +5,6 @@ import (
 )
 
 type BasePlugin struct {
-	Mediator types.Mediator
+	Mediator   types.Mediator
+	Kontroller types.KernelController
 }