feat(kernel): add universal navigator (#54)

.vscode/settings.json

@@ -5,6 +5,7 @@
   ],
   "cSpell.words": [
     "alloc",
+    "argh",
     "astrolib",
     "Berthe",
     "bodyclose",
@@ -20,6 +21,7 @@
     "dogsled",
     "dotenv",
     "dupl",
+    "ents",
     "errcheck",
     "Errorf",
     "exportloopref",
@@ -54,6 +56,7 @@
     "mattn",
     "musico",
     "nakedret",
+    "navi",
     "nolint",
     "nolintlint",
     "onsi",
@@ -63,6 +66,7 @@
     "pixa",
     "prealloc",
     "repotoken",
+    "rsys",
     "samber",
     "shogo",
     "sidewalk",

builders.go

@@ -15,53 +15,62 @@ type buildArtefacts struct {
 }
 
 type Builders struct {
-	fs        pref.FsBuilder
-	options   optionsBuilder
-	navigator kernel.NavigatorBuilder
-	plugins   pluginsBuilder
-	extent    extentBuilder
+	filesystem pref.FileSystemBuilder
+	options    optionsBuilder
+	navigator  kernel.NavigatorBuilder
+	plugins    pluginsBuilder
+	extent     extentBuilder
 }
 
 func (bs *Builders) buildAll() (*buildArtefacts, error) {
-	ext := bs.extent.build(bs.fs.Build())
+	// BUILD FILE SYSTEM & EXTENT
+	//
+	ext := bs.extent.build(bs.filesystem.Build())
 
+	// BUILD OPTIONS
+	//
 	o, optionsErr := bs.options.build(ext)
 	if optionsErr != nil {
-		had := kernel.HadesNav(optionsErr)
-
 		return &buildArtefacts{
 			o:   o,
-			nav: had,
+			nav: kernel.HadesNav(optionsErr),
 			ext: ext,
 		}, optionsErr
 	}
 
-	artefacts, navErr := bs.navigator.Build(o)
+	// BUILD NAVIGATOR
+	//
+	artefacts, navErr := bs.navigator.Build(o, &types.Resources{
+		FS: types.FileSystems{
+			N: ext.navFS(),
+			R: ext.resFS(),
+		},
+	})
 	if navErr != nil {
-		had := kernel.HadesNav(navErr)
-
 		return &buildArtefacts{
 			o:   o,
-			nav: had,
+			nav: kernel.HadesNav(navErr),
 			ext: ext,
 		}, navErr
 	}
 
+	// BUILD PLUGINS
+	//
 	plugins, pluginsErr := bs.plugins.build(o,
 		artefacts.Mediator,
 		ext.plugin(artefacts.Mediator),
 	)
 
 	if pluginsErr != nil {
-		had := kernel.HadesNav(pluginsErr)
-
 		return &buildArtefacts{
 			o:   o,
-			nav: had,
+			nav: kernel.HadesNav(pluginsErr),
 			ext: ext,
 		}, pluginsErr
 	}
 
+	// INIT PLUGINS
+	//
 	for _, p := range plugins {
 		if bindErr := p.Init(); bindErr != nil {
 			return &buildArtefacts{

core/core-defs.go

@@ -1,7 +1,7 @@
 package core
 
-// core contains universal definitions and handles cross cutting concerns
-// try to keep to a minimum to reduce rippling changes
+// core contains universal definitions and handles user facing cross
+// cutting concerns try to keep to a minimum to reduce rippling changes.
 
 type (
 	// TraverseResult

core/directory-contents.go

@@ -8,7 +8,7 @@ import (
 // handles sorting order which by default is different between various
 // operating systems. This abstraction removes the differences in sorting
 // behaviour on different platforms.
-type DirectoryContents struct {
-	Folders []fs.DirEntry
-	Files   []fs.DirEntry
+type DirectoryContents interface {
+	Folders() []fs.DirEntry
+	Files() []fs.DirEntry
 }

core/hooks.go

@@ -17,7 +17,7 @@ type (
 	// SortHook hook function to define how directory entries are sorted. Does not
 	// have to be set explicitly. This will be set according to the IsCaseSensitive on
 	// the TraverseOptions, but can be overridden if needed.
-	SortHook func(entries []fs.DirEntry, custom ...any) error
+	SortHook func(entries []fs.DirEntry, custom ...any)
 
 	SubPathInfo struct {
 		Root            string

core/node.go

@@ -36,7 +36,7 @@ type Extension struct {
 	Custom  any               // to be set and used by the client
 }
 
-// New create a new node Event
+// New create a new Node
 func New(
 	path string, entry fs.DirEntry, info fs.FileInfo, parent *Node, err error,
 ) *Node {
@@ -53,8 +53,8 @@ func New(
 	return node
 }
 
-// Root creates a new node Event which represents the root of directory
-// tree to traverse.
+// Root creates a new Node which represents the root of the
+// directory tree to traverse.
 func Root(root string, info fs.FileInfo) *Node {
 	node := &Node{
 		Path:     root,
@@ -66,22 +66,21 @@ func Root(root string, info fs.FileInfo) *Node {
 	return node
 }
 
-// Clone makes shallow copy of Event (excluding the error).
+// Clone makes shallow copy of Node (excluding the error).
 func (n *Node) Clone() *Node {
 	c := *n
 	c.Error = nil
 
 	return &c
 }
 
-// IsFolder indicates wether this event is a folder.
+// IsFolder indicates wether this node is a folder.
 func (n *Node) IsFolder() bool {
 	return n.dir
 }
 
 func (n *Node) key() string {
-	// ti.Extension.SubPath
-	return "ti.Extension.SubPath"
+	return n.Extension.SubPath
 }
 
 func isDir(n *Node) bool {

director.go

@@ -61,7 +61,7 @@ func Prime(using *pref.Using, settings ...pref.Option) *Builders {
 	// by a panic.
 	//
 	return &Builders{
-		fs: pref.FileSystem(func() fs.FS {
+		filesystem: pref.FileSystem(func() fs.FS {
 			if using.GetFS != nil {
 				return using.GetFS()
 			}
@@ -88,8 +88,8 @@ func Prime(using *pref.Using, settings ...pref.Option) *Builders {
 
 			return ext.options(settings...)
 		}),
-		navigator: kernel.Builder(func(o *pref.Options) (*kernel.Artefacts, error) {
-			return kernel.New(using, o, &kernel.Benign{}), nil
+		navigator: kernel.Builder(func(o *pref.Options, res *types.Resources) (*kernel.Artefacts, error) {
+			return kernel.New(using, o, &kernel.Benign{}, res), nil
 		}),
 		plugins: features(activated), // swap over features & activated
 	}
@@ -106,7 +106,7 @@ func Resume(was *Was, settings ...pref.Option) *Builders {
 	// path was.
 	//
 	return &Builders{
-		fs: pref.FileSystem(func() fs.FS {
+		filesystem: pref.FileSystem(func() fs.FS {
 			if was.Using.GetFS != nil {
 				return was.Using.GetFS()
 			}
@@ -132,8 +132,8 @@ func Resume(was *Was, settings ...pref.Option) *Builders {
 
 			return ext.options(settings...)
 		}),
-		navigator: kernel.Builder(func(o *pref.Options) (*kernel.Artefacts, error) {
-			artefacts := kernel.New(&was.Using, o, resume.GetSealer(was))
+		navigator: kernel.Builder(func(o *pref.Options, res *types.Resources) (*kernel.Artefacts, error) {
+			artefacts := kernel.New(&was.Using, o, resume.GetSealer(was), res)
 
 			return resume.NewController(was, artefacts), nil
 		}),

enums/entry-type-en.go

@@ -0,0 +1,14 @@
+package enums
+
+// EntryType used to enable selecting directory entry type.
+type EntryType uint
+
+const (
+	// EntryTypeFolder
+	//
+	EntryTypeFolder EntryType = iota // folder-entry
+
+	// EntryTypeFile
+	//
+	EntryTypeFile // file-entry
+)

extent.go

@@ -14,6 +14,8 @@ type extent interface {
 	was() *pref.Was
 	plugin(types.Mediator) types.Plugin
 	options(...pref.Option) (*pref.Options, error)
+	navFS() fs.FS
+	resFS() fs.FS
 }
 
 type fileSystems struct {
@@ -25,6 +27,14 @@ type baseExtent struct {
 	fsys fileSystems
 }
 
+func (ex *baseExtent) navFS() fs.FS {
+	return ex.fsys.nas
+}
+
+func (ex *baseExtent) resFS() fs.FS {
+	return ex.fsys.nas
+}
+
 type primeExtent struct {
 	baseExtent
 	u *pref.Using

factories.go

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

internal/hiber/hibernate-plugin.go

@@ -9,9 +9,7 @@ import (
 )
 
 func IfActive(o *pref.Options, mediator types.Mediator) types.Plugin {
-	active := o.Core.Hibernate.Wake != nil
-
-	if active {
+	if o.Core.Hibernate.Wake != nil {
 		return &Plugin{
 			BasePlugin: kernel.BasePlugin{
 				Mediator: mediator,

internal/kernel/builder.go

@@ -11,15 +11,16 @@ type (
 		Navigator  core.Navigator
 		Mediator   types.Mediator
 		Facilities types.Facilities
+		Resources  *types.Resources
 	}
 
 	NavigatorBuilder interface {
-		Build(o *pref.Options) (*Artefacts, error)
+		Build(o *pref.Options, res *types.Resources) (*Artefacts, error)
 	}
 
-	Builder func(o *pref.Options) (*Artefacts, error)
+	Builder func(o *pref.Options, res *types.Resources) (*Artefacts, error)
 )
 
-func (fn Builder) Build(o *pref.Options) (*Artefacts, error) {
-	return fn(o)
+func (fn Builder) Build(o *pref.Options, res *types.Resources) (*Artefacts, error) {
+	return fn(o, res)
 }