feat(nav): set maximum traversal depth (#159)

xfs/nav/helpers_test.go

@@ -117,6 +117,12 @@ type resumeTE struct {
 	log            bool
 }
 
+type cascadeTE struct {
+	naviTE
+	skim  bool
+	depth uint
+}
+
 type resumeTestProfile struct {
 	filtered   bool
 	prohibited map[string]string

xfs/nav/navigation-periscope.go

@@ -50,8 +50,14 @@ func (p *navigationPeriscope) difference(root, current string) {
 	p._offset = currentSize - rootSize
 }
 
-func (p *navigationPeriscope) descend() {
+func (p *navigationPeriscope) descend(max uint) bool {
+	if max > 0 && p._depth > int(max) {
+		return false
+	}
+
 	p._depth++
+
+	return true
 }
 
 func (p *navigationPeriscope) ascend() {

xfs/nav/navigator-abstract.go

@@ -102,14 +102,21 @@ func (n *navigator) logger() log.Logger {
 	return n.log.Get()
 }
 
-func (n *navigator) descend(navi *NavigationInfo) {
-	navi.frame.periscope.descend()
+func (n *navigator) descend(navi *NavigationInfo) bool {
+	if !navi.frame.periscope.descend(n.o.Store.Behaviours.Cascade.Depth) {
+		return false
+	}
+
 	navi.frame.notifiers.descend.invoke(navi.Item)
+
+	return true
 }
 
-func (n *navigator) ascend(navi *NavigationInfo) {
-	navi.frame.periscope.ascend()
-	navi.frame.notifiers.ascend.invoke(navi.Item)
+func (n *navigator) ascend(navi *NavigationInfo, permit bool) {
+	if permit {
+		navi.frame.periscope.ascend()
+		navi.frame.notifiers.ascend.invoke(navi.Item)
+	}
 }
 
 func (n *navigator) finish() error {

xfs/nav/navigator-files.go

@@ -45,21 +45,25 @@ func (n *filesNavigator) traverse(params *traverseParams) (*TraverseItem, error)
 		Item:    params.current,
 		frame:   params.frame,
 	}
+	params.navi = navi
+	descended := n.descend(navi)
+
 	//
 	// For files, the registered callback will only be invoked for file entries. This means
 	// that the client will have no way to skip the descending of a particular directory. In
 	// this case, the client should use the OnDescend callback (yet to be implemented) and
 	// return SkipDir from there.
-	defer func() {
+	defer func(permit bool) {
 		if n.samplingFilterActive {
 			delete(n.agent.cache, params.current.key())
 		}
 
-		n.ascend(navi)
-	}()
+		n.ascend(navi, permit)
+	}(descended)
 
-	params.navi = navi
-	n.descend(navi)
+	if !descended {
+		return nil, nil
+	}
 
 	stash := n.inspect(params)
 

xfs/nav/navigator-folders.go

@@ -76,16 +76,21 @@ func (n *foldersNavigator) traverse(params *traverseParams) (*TraverseItem, erro
 		Item:    params.current,
 		frame:   params.frame,
 	}
-	defer func() {
+
+	params.navi = navi
+	descended := n.descend(navi)
+
+	defer func(permit bool) {
 		if n.samplingFilterActive {
 			delete(n.agent.cache, params.current.key())
 		}
 
-		n.ascend(navi)
-	}()
+		n.ascend(navi, permit)
+	}(descended)
 
-	params.navi = navi
-	n.descend(navi)
+	if !descended {
+		return nil, nil
+	}
 
 	stash := n.inspect(params)
 	entries := stash.entries

xfs/nav/navigator-universal.go

@@ -49,16 +49,20 @@ func (n *universalNavigator) traverse(params *traverseParams) (*TraverseItem, er
 		frame:   params.frame,
 	}
 
-	defer func() {
+	params.navi = navi
+	descended := n.descend(navi)
+
+	defer func(permit bool) {
 		if n.samplingFilterActive {
 			delete(n.agent.cache, params.current.key())
 		}
 
-		n.ascend(navi)
-	}()
+		n.ascend(navi, permit)
+	}(descended)
 
-	params.navi = navi
-	n.descend(navi)
+	if !descended {
+		return nil, nil
+	}
 
 	stash := n.inspect(params)
 	entries := stash.entries

xfs/nav/sampling-while-iterator.go

@@ -138,7 +138,7 @@ func (i *directoryEntryWhileIt) start(entries []fs.DirEntry) {
 func (i *directoryEntryWhileIt) sample(entries []fs.DirEntry, processingFiles bool) []fs.DirEntry {
 	i.start(entries)
 
-	result := i.loop()
+	result := i.enumerate()
 
 	return lo.Ternary[[]fs.DirEntry](processingFiles, result.Files, result.Folders)
 }
@@ -148,15 +148,15 @@ func (i *directoryEntryWhileIt) samples(
 ) (files, folders []fs.DirEntry) {
 	i.start(sourceEntries.All())
 
-	result := i.loop()
+	result := i.enumerate()
 
 	files = result.Files
 	folders = result.Folders
 
 	return
 }
 
-func (i *directoryEntryWhileIt) loop() *DirectoryContents {
+func (i *directoryEntryWhileIt) enumerate() *DirectoryContents {
 	result := newEmptyDirectoryEntries(i.o, &i.o.Store.Sampling.NoOf)
 	parent := i.tp.current