ref(tv): consolidate file systems into universal (#194)

.vscode/settings.json

@@ -4,6 +4,7 @@
     "--fast"
   ],
   "cSpell.words": [
+    "afero",
     "alloc",
     "Aphex",
     "argh",
@@ -107,11 +108,13 @@
     "toplevel",
     "tparallel",
     "trimprefix",
+    "tsys",
     "Turan",
     "typecheck",
     "unconvert",
     "unlambda",
     "unparam",
+    "usys",
     "vals",
     "varcheck",
     "verr",

builders.go

@@ -16,23 +16,24 @@ type buildArtefacts struct {
 	ext     extent
 }
 
+// Builders performs build orchestration via its buildAll method. Builders
+// is instructed by the factories (via Configure) of which there are 2; one
+// for Walk and one for Run. The Prime/Resume extents create the Builders
+// instance.
 type Builders struct {
-	using     *pref.Using
-	readerFS  pref.ReadDirFileSystemBuilder
-	queryFS   pref.QueryStatusFileSystemBuilder
-	options   optionsBuilder
-	navigator kernel.NavigatorBuilder
-	plugins   pluginsBuilder
-	extent    extentBuilder
+	using       *pref.Using
+	universalFS pref.TraverseFileSystemBuilder
+	options     optionsBuilder
+	navigator   kernel.NavigatorBuilder
+	plugins     pluginsBuilder
+	extent      extentBuilder
 }
 
 func (bs *Builders) buildAll() (*buildArtefacts, error) {
 	// BUILD FILE SYSTEM & EXTENT
 	//
-	reader := bs.readerFS.Build()
 	ext := bs.extent.build(
-		reader,
-		bs.queryFS.Build(reader),
+		bs.universalFS.Build(bs.using.Root),
 	)
 
 	// BUILD OPTIONS
@@ -50,9 +51,7 @@ func (bs *Builders) buildAll() (*buildArtefacts, error) {
 	//
 	artefacts, navErr := bs.navigator.Build(o, &types.Resources{
 		FS: FileSystems{
-			N: ext.navFS(),
-			Q: ext.queryFS(),
-			R: ext.resFS(),
+			T: ext.traverseFS(),
 		},
 		Supervisor: measure.New(),
 		Binder:     binder,

director-prime_test.go

@@ -12,13 +12,18 @@ import (
 	"github.com/snivilised/traverse/core"
 	"github.com/snivilised/traverse/cycle"
 	"github.com/snivilised/traverse/enums"
+	lab "github.com/snivilised/traverse/internal/laboratory"
 	"github.com/snivilised/traverse/internal/opts"
 	"github.com/snivilised/traverse/internal/services"
 	"github.com/snivilised/traverse/locale"
 	"github.com/snivilised/traverse/pref"
 )
 
 var _ = Describe("Director(Prime)", Ordered, func() {
+	var (
+		root string
+	)
+
 	BeforeAll(func() {
 		Expect(li18ngo.Use(
 			func(o *li18ngo.UseOptions) {
@@ -27,6 +32,8 @@ var _ = Describe("Director(Prime)", Ordered, func() {
 				}
 			},
 		)).To(Succeed())
+
+		root = lab.Repo("test")
 	})
 
 	BeforeEach(func() {
@@ -44,7 +51,7 @@ var _ = Describe("Director(Prime)", Ordered, func() {
 
 					_, err := tv.Walk().Configure().Extent(tv.Prime(
 						&tv.Using{
-							Root:         RootPath,
+							Root:         root,
 							Subscription: tv.SubscribeFiles,
 							Handler:      noOpHandler,
 						},

director-resume_test.go

@@ -2,7 +2,6 @@ package tv_test
 
 import (
 	"context"
-	"io/fs"
 	"os"
 	"sync"
 	"testing/fstest"
@@ -16,14 +15,16 @@ import (
 	"github.com/snivilised/traverse/core"
 	"github.com/snivilised/traverse/cycle"
 	"github.com/snivilised/traverse/enums"
+	lab "github.com/snivilised/traverse/internal/laboratory"
 	"github.com/snivilised/traverse/internal/services"
+	"github.com/snivilised/traverse/lfs"
 	"github.com/snivilised/traverse/locale"
 	"github.com/snivilised/traverse/pref"
 )
 
 var _ = Describe("Director(Resume)", Ordered, func() {
 	var (
-		emptyFS fstest.MapFS
+		emptyFS *lab.TestTraverseFS
 		restore pref.Option
 	)
 
@@ -33,9 +34,11 @@ var _ = Describe("Director(Resume)", Ordered, func() {
 
 			return nil
 		}
-		emptyFS = fstest.MapFS{
-			".": &fstest.MapFile{
-				Mode: os.ModeDir,
+		emptyFS = &lab.TestTraverseFS{
+			MapFS: fstest.MapFS{
+				".": &fstest.MapFile{
+					Mode: os.ModeDir,
+				},
 			},
 		}
 
@@ -67,10 +70,7 @@ var _ = Describe("Director(Resume)", Ordered, func() {
 						Using: tv.Using{
 							Subscription: tv.SubscribeFiles,
 							Handler:      noOpHandler,
-							GetReadDirFS: func() fs.ReadDirFS {
-								return emptyFS
-							},
-							GetQueryStatusFS: func(_ fs.FS) fs.StatFS {
+							GetTraverseFS: func(_ string) lfs.TraverseFS {
 								return emptyFS
 							},
 						},

director.go

@@ -1,8 +1,6 @@
 package tv
 
 import (
-	"io/fs"
-
 	"github.com/snivilised/traverse/internal/feat/filter"
 	"github.com/snivilised/traverse/internal/feat/hiber"
 	"github.com/snivilised/traverse/internal/feat/nanny"
@@ -12,10 +10,19 @@ import (
 	"github.com/snivilised/traverse/internal/opts"
 	"github.com/snivilised/traverse/internal/third/lo"
 	"github.com/snivilised/traverse/internal/types"
+	"github.com/snivilised/traverse/lfs"
 	"github.com/snivilised/traverse/pref"
 )
 
-type ifActive func(o *pref.Options, using *pref.Using, mediator types.Mediator) types.Plugin
+const (
+	noOverwrite = true
+)
+
+type (
+	ifActive func(o *pref.Options,
+		using *pref.Using, mediator types.Mediator,
+	) types.Plugin
+)
 
 // features interrogates options and invokes requests on behalf of the user
 // to activate features according to option selections. other plugins will
@@ -69,33 +76,20 @@ func features(o *pref.Options, using *pref.Using, mediator types.Mediator,
 // Prime extent requests that the navigator performs a full
 // traversal from the root path specified.
 func Prime(using *pref.Using, settings ...pref.Option) *Builders {
-	// TODO: we need to create an aux file system, which is bound
-	// to a pre-defined location, that will be called upon if
-	// the navigation session is terminated either by a ctrl-c or
-	// by a panic.
-	//
 	return &Builders{
 		using: using,
-		readerFS: pref.CreateReadDirFS(func() fs.ReadDirFS {
-			if using.GetReadDirFS != nil {
-				return using.GetReadDirFS()
+		universalFS: pref.CreateTraverseFS(func(root string) lfs.TraverseFS {
+			if using.GetTraverseFS != nil {
+				return using.GetTraverseFS(root)
 			}
 
-			return NewLocalFS(using.Root)
+			return lfs.NewTraverseFS(root, noOverwrite)
 		}),
-		queryFS: pref.CreateQueryStatusFS(func(qsys fs.FS) fs.StatFS {
-			if using.GetQueryStatusFS != nil {
-				return using.GetQueryStatusFS(qsys)
-			}
-
-			return NewQueryStatusFS(qsys)
-		}),
-		extent: extension(func(rsys fs.ReadDirFS, qsys fs.StatFS) extent {
+		extent: extension(func(tsys lfs.TraverseFS) extent {
 			return &primeExtent{
 				baseExtent: baseExtent{
 					fileSys: fileSystems{
-						nas: rsys,
-						qus: qsys,
+						tsys: tsys,
 					},
 				},
 				u: using,
@@ -130,32 +124,20 @@ func Prime(using *pref.Using, settings ...pref.Option) *Builders {
 // as a result of it being terminated prematurely via a ctrl-c
 // interrupt.
 func Resume(was *Was, settings ...pref.Option) *Builders {
-	// TODO: the navigation file system, baseExtent.sys, will be set for
-	// resume, only once the resume file has been loaded, as
-	// its only at this point, we know where the original root
-	// path was.
-	//
 	return &Builders{
 		using: &was.Using,
-		readerFS: pref.CreateReadDirFS(func() fs.ReadDirFS {
-			if was.Using.GetReadDirFS != nil {
-				return was.Using.GetReadDirFS()
-			}
-			return NewLocalFS(was.Root)
-		}),
-		queryFS: pref.CreateQueryStatusFS(func(fsys fs.FS) fs.StatFS {
-			if was.Using.GetQueryStatusFS != nil {
-				return was.Using.GetQueryStatusFS(fsys)
+		universalFS: pref.CreateTraverseFS(func(root string) lfs.TraverseFS {
+			if was.Using.GetTraverseFS != nil {
+				return was.Using.GetTraverseFS(root)
 			}
 
-			return NewQueryStatusFS(fsys)
+			return lfs.NewTraverseFS(root, noOverwrite)
 		}),
-		extent: extension(func(rsys fs.ReadDirFS, qsys fs.StatFS) extent {
+		extent: extension(func(tsys lfs.TraverseFS) extent {
 			return &resumeExtent{
 				baseExtent: baseExtent{
 					fileSys: fileSystems{
-						nas: rsys,
-						qus: qsys,
+						tsys: tsys,
 					},
 				},
 				w: was,

extent.go

@@ -1,12 +1,11 @@
 package tv
 
 import (
-	"io/fs"
-
 	"github.com/snivilised/traverse/internal/feat/resume"
 	"github.com/snivilised/traverse/internal/kernel"
 	"github.com/snivilised/traverse/internal/opts"
 	"github.com/snivilised/traverse/internal/types"
+	"github.com/snivilised/traverse/lfs"
 	"github.com/snivilised/traverse/pref"
 )
 
@@ -15,32 +14,20 @@ type extent interface {
 	was() *pref.Was
 	plugin(*kernel.Artefacts) types.Plugin
 	options(...pref.Option) (*pref.Options, *opts.Binder, error)
-	navFS() fs.ReadDirFS
-	queryFS() fs.StatFS
-	resFS() fs.FS
+	traverseFS() lfs.TraverseFS
 	complete() bool
 }
 
 type fileSystems struct {
-	nas fs.ReadDirFS
-	qus fs.StatFS
-	res fs.FS
+	tsys lfs.TraverseFS
 }
 
 type baseExtent struct {
 	fileSys fileSystems
 }
 
-func (ex *baseExtent) navFS() fs.ReadDirFS {
-	return ex.fileSys.nas
-}
-
-func (ex *baseExtent) queryFS() fs.StatFS {
-	return ex.fileSys.qus
-}
-
-func (ex *baseExtent) resFS() fs.FS {
-	return ex.fileSys.nas
+func (ex *baseExtent) traverseFS() lfs.TraverseFS {
+	return ex.fileSys.tsys
 }
 
 type primeExtent struct {
@@ -95,7 +82,7 @@ func (ex *resumeExtent) plugin(artefacts *kernel.Artefacts) types.Plugin {
 }
 
 func (ex *resumeExtent) options(settings ...pref.Option) (*pref.Options, *opts.Binder, error) {
-	loaded, binder, err := resume.Load(ex.fileSys.res, ex.w.From, settings...)
+	loaded, binder, err := resume.Load(ex.fileSys.tsys, ex.w.From, settings...)
 	ex.loaded = loaded
 
 	// TODO: get the resume point from the resume persistence file

internal-traverse-defs.go

@@ -5,6 +5,7 @@ import (
 
 	"github.com/snivilised/traverse/internal/opts"
 	"github.com/snivilised/traverse/internal/types"
+	"github.com/snivilised/traverse/lfs"
 	"github.com/snivilised/traverse/pref"
 )
 
@@ -56,13 +57,13 @@ func (fn filesystem) build(path string) fs.FS {
 }
 
 type extentBuilder interface {
-	build(rsys fs.ReadDirFS, qsys fs.StatFS) extent
+	build(tsys lfs.TraverseFS) extent
 }
 
-type extension func(rsys fs.ReadDirFS, qsys fs.StatFS) extent
+type extension func(tsys lfs.TraverseFS) extent
 
-func (fn extension) build(rsys fs.ReadDirFS, qsys fs.StatFS) extent {
-	return fn(rsys, qsys)
+func (fn extension) build(tsys lfs.TraverseFS) extent {
+	return fn(tsys)
 }
 
 // We need an entity that manages the decoration of the client handler. The

internal/feat/hiber/hibernate_test.go

@@ -4,7 +4,6 @@ import (
 	"fmt"
 	"io/fs"
 	"path/filepath"
-	"testing/fstest"
 
 	. "github.com/onsi/ginkgo/v2" //nolint:revive // ok
 	. "github.com/onsi/gomega"    //nolint:revive // ok
@@ -17,11 +16,12 @@ import (
 	lab "github.com/snivilised/traverse/internal/laboratory"
 	"github.com/snivilised/traverse/internal/services"
 	"github.com/snivilised/traverse/internal/third/lo"
+	"github.com/snivilised/traverse/lfs"
 )
 
 var _ = Describe("feature", Ordered, func() {
 	var (
-		FS   fstest.MapFS
+		FS   *lab.TestTraverseFS
 		root string
 	)
 
@@ -57,10 +57,7 @@ var _ = Describe("feature", Ordered, func() {
 								)
 								return nil
 							},
-							GetReadDirFS: func() fs.ReadDirFS {
-								return FS
-							},
-							GetQueryStatusFS: func(_ fs.FS) fs.StatFS {
+							GetTraverseFS: func(_ string) lfs.TraverseFS {
 								return FS
 							},
 						},
@@ -154,10 +151,7 @@ var _ = Describe("feature", Ordered, func() {
 					Root:         path,
 					Subscription: entry.Subscription,
 					Handler:      client,
-					GetReadDirFS: func() fs.ReadDirFS {
-						return FS
-					},
-					GetQueryStatusFS: func(_ fs.FS) fs.StatFS {
+					GetTraverseFS: func(_ string) lfs.TraverseFS {
 						return FS
 					},
 				},