feat(nav): implement directory sampling (#369)

feat(nav): implement file sampler (#369)

feat(nav): implement folder sampler (#369)

feat(nav): implement universal sampler (#369)

ref(nav): remove redundant order field from directory entries (#369)

ref(nav): remove frivolous factories (#369)

ref(nav): tidy up xi18n/i18n imports (#369)

internal/helpers/test-utilities.go

@@ -7,7 +7,7 @@ import (
 	"runtime"
 	"strings"
 
-	xi18n "github.com/snivilised/extendio/i18n"
+	"github.com/snivilised/extendio/i18n"
 	"github.com/snivilised/extendio/xfs/nav"
 )
 
@@ -24,6 +24,12 @@ func Reason(name string) string {
 	return fmt.Sprintf("❌ for item named: '%v'", name)
 }
 
+func BecauseQuantity(name string, expected, actual int) string {
+	return fmt.Sprintf("❌ incorrect no of items for: '%v', expected: '%v', actual: '%v'",
+		name, expected, actual,
+	)
+}
+
 func JoinCwd(segments ...string) string {
 	if current, err := os.Getwd(); err == nil {
 		parent, _ := filepath.Split(current)
@@ -98,8 +104,8 @@ type DummyCreator struct {
 	Invoked bool
 }
 
-func (dc *DummyCreator) Create(_ *xi18n.LanguageInfo, _ string) (*xi18n.Localizer, error) {
+func (dc *DummyCreator) Create(_ *i18n.LanguageInfo, _ string) (*i18n.Localizer, error) {
 	dc.Invoked = true
 
-	return &xi18n.Localizer{}, nil
+	return &i18n.Localizer{}, nil
 }

internal/log/new-logger.go

@@ -7,14 +7,14 @@ import (
 	"go.uber.org/zap"
 	"go.uber.org/zap/zapcore"
 
-	xi18n "github.com/snivilised/extendio/i18n"
+	"github.com/snivilised/extendio/i18n"
 )
 
 func NewLogger(info *LoggerInfo) Ref {
 	return utils.NewRoProp(lo.TernaryF(info.Enabled,
 		func() Logger {
 			if info.Path == "" {
-				panic(xi18n.NewInvalidConfigEntryError(info.Path, "Store/Logging/Path"))
+				panic(i18n.NewInvalidConfigEntryError(info.Path, "Store/Logging/Path"))
 			}
 			ws := zapcore.AddSync(&lumberjack.Logger{
 				Filename:   info.Path,

xfs/nav/directory-entries.go

@@ -1,11 +1,10 @@
 package nav
 
 import (
-	"fmt"
 	"io/fs"
 
 	"github.com/samber/lo"
-	xi18n "github.com/snivilised/extendio/i18n"
+	"github.com/snivilised/extendio/i18n"
 )
 
 // DirectoryEntryOrderEnum determines what order a directories
@@ -20,36 +19,44 @@ const (
 	DirectoryEntryOrderFilesFirstEn
 )
 
-type directoryEntriesFactory struct{}
-
-type directoryEntriesFactoryParams struct {
+type newDirectoryEntriesParams struct {
 	o       *TraverseOptions
-	order   DirectoryEntryOrderEnum
 	entries []fs.DirEntry
 }
 
-func (directoryEntriesFactory) new(params *directoryEntriesFactoryParams) *DirectoryEntries {
+func newDirectoryEntries(params *newDirectoryEntriesParams) *DirectoryEntries {
 	instance := DirectoryEntries{
 		Options: params.o,
-		Order:   params.order,
 	}
 
 	instance.arrange(params.entries)
 
 	return &instance
 }
 
-// DirectoryEntries
+// DirectoryEntries represents the contents of a directory's contents and
+// handles sorting order which by default is different between various
+// operating systems. This abstraction removes the differences in sorting
+// behaviour on different platforms.
 type DirectoryEntries struct {
 	Options *TraverseOptions
-	Order   DirectoryEntryOrderEnum
 	Folders []fs.DirEntry
 	Files   []fs.DirEntry
 }
 
-func (e *DirectoryEntries) Sample() *DirectoryEntries {
-	fmt.Println("❌❌❌ DirectoryEntries.Sample NOT-IMPLEMENTED")
-	return e
+// All returns the contents of a directory respecting the directory sorting
+// order defined in the traversal options.
+func (e *DirectoryEntries) All() []fs.DirEntry {
+	result := []fs.DirEntry{}
+
+	switch e.Options.Store.Behaviours.Sort.DirectoryEntryOrder {
+	case DirectoryEntryOrderFoldersFirstEn:
+		result = append(e.Folders, e.Files...) //nolint:gocritic // no alternative known
+	case DirectoryEntryOrderFilesFirstEn:
+		result = append(e.Files, e.Folders...) //nolint:gocritic // no alternative known
+	}
+
+	return result
 }
 
 func (e *DirectoryEntries) arrange(entries []fs.DirEntry) {
@@ -69,21 +76,16 @@ func (e *DirectoryEntries) arrange(entries []fs.DirEntry) {
 	}
 }
 
-func (e *DirectoryEntries) all() []fs.DirEntry {
-	result := []fs.DirEntry{}
-
-	switch e.Order {
-	case DirectoryEntryOrderFoldersFirstEn:
-		result = append(e.Folders, e.Files...) //nolint:gocritic // no alternative known
-	case DirectoryEntryOrderFilesFirstEn:
-		result = append(e.Files, e.Folders...) //nolint:gocritic // no alternative known
+func (e *DirectoryEntries) sort(entries []fs.DirEntry) {
+	if err := e.Options.Hooks.Sort(entries); err != nil {
+		panic(i18n.NewSortFnFailedError())
 	}
-
-	return result
 }
 
-func (e *DirectoryEntries) sort(entries []fs.DirEntry) {
-	if err := e.Options.Hooks.Sort(entries); err != nil {
-		panic(xi18n.NewSortFnFailedError())
+func newEmptyDirectoryEntries(o *TraverseOptions) *DirectoryEntries {
+	return &DirectoryEntries{
+		Options: o,
+		Files:   []fs.DirEntry{},
+		Folders: []fs.DirEntry{},
 	}
 }

xfs/nav/error-handlers.go

@@ -5,7 +5,7 @@ import (
 	"os"
 
 	"github.com/samber/lo"
-	xi18n "github.com/snivilised/extendio/i18n"
+	"github.com/snivilised/extendio/i18n"
 )
 
 type fileSystemErrorParams struct {
@@ -26,10 +26,10 @@ type notifyCallbackErrorHandler struct {
 func (h *notifyCallbackErrorHandler) accept(params *fileSystemErrorParams) error {
 	err := lo.TernaryF(os.IsNotExist(params.err),
 		func() error {
-			return xi18n.NewPathNotFoundError("Traverse Item", params.path)
+			return i18n.NewPathNotFoundError("Traverse Item", params.path)
 		},
 		func() error {
-			return xi18n.NewThirdPartyErr(params.err)
+			return i18n.NewThirdPartyErr(params.err)
 		},
 	)
 

xfs/nav/helpers_test.go

@@ -54,9 +54,10 @@ type skipTE struct {
 
 type sampleTE struct {
 	naviTE
-	filter    *filterTE
-	noOf      nav.SampleNoOf
-	useLastFn bool
+	filter       *filterTE
+	noOf         nav.SampleNoOf
+	useLastFn    bool
+	expectedNoOf directoryQuantities
 }
 
 type listenTE struct {

xfs/nav/marshal-state.go

@@ -4,7 +4,7 @@ import (
 	"encoding/json"
 	"os"
 
-	xi18n "github.com/snivilised/extendio/i18n"
+	"github.com/snivilised/extendio/i18n"
 )
 
 type stateMarshallerJSON struct {
@@ -48,7 +48,7 @@ func (m *stateMarshallerJSON) unmarshal(path string) error {
 
 func (m *stateMarshallerJSON) validate() {
 	if m.o.Callback.Fn == nil {
-		panic(xi18n.NewMissingCallbackError())
+		panic(i18n.NewMissingCallbackError())
 	}
 }
 

xfs/nav/navigation-agent.go

@@ -5,19 +5,17 @@ import (
 	"io/fs"
 	"path/filepath"
 
-	xi18n "github.com/snivilised/extendio/i18n"
+	"github.com/snivilised/extendio/i18n"
 	"github.com/snivilised/extendio/xfs/utils"
 )
 
-type agentFactory struct{}
-type agentFactoryParams struct {
-	doInvoke  bool
-	o         *TraverseOptions
-	deFactory directoryEntriesFactory
-	handler   fileSystemErrorHandler
+type newAgentParams struct {
+	doInvoke bool
+	o        *TraverseOptions
+	handler  fileSystemErrorHandler
 }
 
-func (agentFactory) new(params *agentFactoryParams) *navigationAgent {
+func newAgent(params *newAgentParams) *navigationAgent {
 	instance := navigationAgent{
 		doInvoke: utils.NewRoProp(params.doInvoke),
 		o:        params.o,
@@ -76,30 +74,26 @@ func (a *navigationAgent) top(params *agentTopParams) (*TraverseResult, error) {
 
 func (a *navigationAgent) read(
 	path string,
-	order DirectoryEntryOrderEnum,
 ) (*DirectoryEntries, error) {
 	// this method was spun out from notify, as there needs to be a separation
 	// between these pieces of functionality to support 'extension'; ie we
 	// need to read the contents of an items contents to determine the properties
 	// created for the extension.
 	//
 	entries, err := a.o.Hooks.ReadDirectory(path)
-
-	deFactory := directoryEntriesFactory{}
-	de := deFactory.new(&directoryEntriesFactoryParams{
+	de := newDirectoryEntries(&newDirectoryEntriesParams{
 		o:       a.o,
-		order:   order,
 		entries: entries,
 	})
 
 	return de, err
 }
 
 type agentNotifyParams struct {
-	frame   *navigationFrame
-	item    *TraverseItem
-	entries []fs.DirEntry
-	readErr error
+	frame    *navigationFrame
+	item     *TraverseItem
+	contents []fs.DirEntry
+	readErr  error
 }
 
 func (a *navigationAgent) notify(params *agentNotifyParams) (SkipTraversal, error) {
@@ -108,7 +102,7 @@ func (a *navigationAgent) notify(params *agentNotifyParams) (SkipTraversal, erro
 	if params.readErr != nil {
 		if a.doInvoke.Get() {
 			item2 := params.item.clone()
-			item2.Error = xi18n.NewThirdPartyErr(params.readErr)
+			item2.Error = i18n.NewThirdPartyErr(params.readErr)
 
 			// Second call, to report ReadDir error
 			//
@@ -117,10 +111,10 @@ func (a *navigationAgent) notify(params *agentNotifyParams) (SkipTraversal, erro
 					params.readErr = nil
 				}
 
-				return SkipTraversalAllEn, xi18n.NewThirdPartyErr(params.readErr)
+				return SkipTraversalAllEn, i18n.NewThirdPartyErr(params.readErr)
 			}
 		} else {
-			return SkipTraversalAllEn, xi18n.NewThirdPartyErr(params.readErr)
+			return SkipTraversalAllEn, i18n.NewThirdPartyErr(params.readErr)
 		}
 	}
 

xfs/nav/navigation-listener.go

@@ -2,7 +2,7 @@ package nav
 
 import (
 	"github.com/snivilised/extendio/collections"
-	xi18n "github.com/snivilised/extendio/i18n"
+	"github.com/snivilised/extendio/i18n"
 )
 
 // ListenHandler
@@ -141,7 +141,7 @@ func (l *navigationListener) makeStates(params *listenStatesParams) {
 		ListenRetired: &LabelledTraverseCallback{
 			Label: "ListenRetired decorator",
 			Fn: func(_ *TraverseItem) error {
-				return xi18n.NewTerminateTraverseError()
+				return i18n.NewTerminateTraverseError()
 			},
 		},
 	}

xfs/nav/navigation-session.go

@@ -4,7 +4,7 @@ import (
 	"errors"
 	"time"
 
-	xi18n "github.com/snivilised/extendio/i18n"
+	"github.com/snivilised/extendio/i18n"
 )
 
 type Session interface {
@@ -125,7 +125,7 @@ func (s *Resume) init() {
 	})
 
 	if err != nil {
-		panic(xi18n.NewFailedToResumeFromFileError(s.RestorePath, err))
+		panic(i18n.NewFailedToResumeFromFileError(s.RestorePath, err))
 	}
 }
 

xfs/nav/navigator-files.go

@@ -1,5 +1,7 @@
 package nav
 
+import "io/fs"
+
 type filesNavigator struct {
 	navigator
 }
@@ -33,24 +35,22 @@ func (n *filesNavigator) traverse(params *traverseParams) (*TraverseItem, error)
 	}
 
 	var (
-		entries *DirectoryEntries
-		readErr error
-		isDir   = params.item.IsDir()
+		entries  *DirectoryEntries
+		contents []fs.DirEntry
+		readErr  error
+		isDir    = params.item.IsDir()
 	)
 
 	if isDir {
-		entries, readErr = n.agent.read(
-			params.item.Path,
-			n.o.Store.Behaviours.Sort.DirectoryEntryOrder,
-		)
+		entries, readErr = n.agent.read(params.item.Path)
 
 		// Files and Folders need to be sorted independently to preserve the navigation order
 		// stipulated by .Behaviours.Sort.DirectoryEntryOrder
 		//
 		entries.sort(entries.Files)
 		entries.sort(entries.Folders)
 	} else {
-		entries = &DirectoryEntries{}
+		entries = newEmptyDirectoryEntries(n.o)
 	}
 
 	if !isDir {
@@ -61,15 +61,17 @@ func (n *filesNavigator) traverse(params *traverseParams) (*TraverseItem, error)
 		return nil, params.frame.proxy(params.item, nil)
 	}
 
-	// sample here
+	if n.o.isSamplingActive() {
+		n.o.Sampler.Fn(entries)
+	}
 
-	sorted := entries.all()
+	contents = entries.All()
 
 	if skip, err := n.agent.notify(&agentNotifyParams{
-		frame:   params.frame,
-		item:    params.item,
-		entries: sorted,
-		readErr: readErr,
+		frame:    params.frame,
+		item:     params.item,
+		contents: contents,
+		readErr:  readErr,
 	}); skip == SkipTraversalAllEn || err != nil {
 		return nil, err
 	} else if skip == SkipTraversalDirEn {
@@ -78,7 +80,7 @@ func (n *filesNavigator) traverse(params *traverseParams) (*TraverseItem, error)
 
 	return n.agent.traverse(&agentTraverseParams{
 		impl:     n,
-		contents: sorted,
+		contents: contents,
 		parent:   params.item,
 		frame:    params.frame,
 	})