[STEP-2135] Migrate pathutil filters and sortable path to v2

Adds the v1 pathutil filter and sort helpers to v2:

- FilterFS walker over fs.FS with FilterFunc(pth, fs.DirEntry)
- Factories: Base, Extension, Regexp, Component, ComponentWithExtension,
  IsDirectory, InDirectory, SkipDirectoryName, DirectoryContainsFile, FileContains
- v1-compat adapters FilterPaths([]string) and ListEntries(dir) so existing
  callers migrate by import-path rename only
- Sortable path helpers: SortablePath, NewSortablePath,
  BySortablePathComponents, SortPathsByComponents, ListPathInDirSortedByComponents

Author: Badlazzor

pathutil/path_filter.go

@@ -0,0 +1,155 @@
+package pathutil
+
+import (
+	"errors"
+	"io/fs"
+	"path"
+	"regexp"
+	"slices"
+	"strings"
+)
+
+// FilterFunc decides whether an entry produced by an fs.FS walk should be
+// kept. The path is slash-separated and rooted at the fs root ("." for the
+// root itself). Returning fs.SkipDir as the error skips the current
+// directory's subtree.
+type FilterFunc func(pth string, d fs.DirEntry) (bool, error)
+
+// FilterFS walks fsys recursively and returns every path for which all
+// filters return true. Paths are slash-separated and relative to fsys.
+func FilterFS(fsys fs.FS, filters ...FilterFunc) ([]string, error) {
+	var filtered []string
+
+	err := fs.WalkDir(fsys, ".", func(pth string, d fs.DirEntry, walkErr error) error {
+		if walkErr != nil {
+			return walkErr
+		}
+
+		for _, filter := range filters {
+			matches, err := filter(pth, d)
+			if err != nil {
+				return err
+			}
+			if !matches {
+				return nil
+			}
+		}
+
+		filtered = append(filtered, pth)
+		return nil
+	})
+	if err != nil {
+		return nil, err
+	}
+	return filtered, nil
+}
+
+// BaseFilter matches entries whose base name equals base (case-insensitive).
+// When allowed is false the match is inverted.
+func BaseFilter(base string, allowed bool) FilterFunc {
+	return func(pth string, _ fs.DirEntry) (bool, error) {
+		return allowed == strings.EqualFold(path.Base(pth), base), nil
+	}
+}
+
+// ExtensionFilter matches entries whose extension equals ext
+// (case-insensitive, leading dot included, e.g. ".txt").
+func ExtensionFilter(ext string, allowed bool) FilterFunc {
+	return func(pth string, _ fs.DirEntry) (bool, error) {
+		return allowed == strings.EqualFold(path.Ext(pth), ext), nil
+	}
+}
+
+// RegexpFilter matches entries whose path contains a match for pattern.
+// The pattern is compiled once when the filter is constructed.
+func RegexpFilter(pattern string, allowed bool) FilterFunc {
+	re := regexp.MustCompile(pattern)
+	return func(pth string, _ fs.DirEntry) (bool, error) {
+		return allowed == (re.FindString(pth) != ""), nil
+	}
+}
+
+// ComponentFilter matches entries whose path contains component as one of
+// its slash-separated components.
+func ComponentFilter(component string, allowed bool) FilterFunc {
+	return func(pth string, _ fs.DirEntry) (bool, error) {
+		found := slices.Contains(strings.Split(pth, "/"), component)
+		return allowed == found, nil
+	}
+}
+
+// ComponentWithExtensionFilter matches entries whose path has at least one
+// component with the given extension.
+func ComponentWithExtensionFilter(ext string, allowed bool) FilterFunc {
+	return func(pth string, _ fs.DirEntry) (bool, error) {
+		found := slices.ContainsFunc(strings.Split(pth, "/"), func(c string) bool {
+			return path.Ext(c) == ext
+		})
+		return allowed == found, nil
+	}
+}
+
+// IsDirectoryFilter matches entries based on whether they are directories.
+func IsDirectoryFilter(allowed bool) FilterFunc {
+	return func(_ string, d fs.DirEntry) (bool, error) {
+		if d == nil {
+			return false, errors.New("no directory entry available")
+		}
+		return allowed == d.IsDir(), nil
+	}
+}
+
+// InDirectoryFilter matches entries whose direct parent directory equals dir.
+func InDirectoryFilter(dir string, allowed bool) FilterFunc {
+	return func(pth string, _ fs.DirEntry) (bool, error) {
+		return allowed == (path.Dir(pth) == dir), nil
+	}
+}
+
+// SkipDirectoryNameFilter keeps every non-directory entry. When it encounters
+// a directory whose base name matches dirName (case-insensitive) it returns
+// fs.SkipDir so the whole subtree is skipped.
+func SkipDirectoryNameFilter(dirName string) FilterFunc {
+	return func(pth string, d fs.DirEntry) (bool, error) {
+		if d == nil || !d.IsDir() {
+			return true, nil
+		}
+		if strings.EqualFold(path.Base(pth), dirName) {
+			return false, fs.SkipDir
+		}
+		return true, nil
+	}
+}
+
+// DirectoryContainsFileFilter matches directories that contain a regular
+// file named fileName. fsys is used to stat the candidate path.
+func DirectoryContainsFileFilter(fsys fs.FS, fileName string) FilterFunc {
+	return func(pth string, d fs.DirEntry) (bool, error) {
+		if d == nil || !d.IsDir() {
+			return false, nil
+		}
+		info, err := fs.Stat(fsys, path.Join(pth, fileName))
+		if err != nil {
+			if errors.Is(err, fs.ErrNotExist) {
+				return false, nil
+			}
+			return false, err
+		}
+		return !info.IsDir(), nil
+	}
+}
+
+// FileContainsFilter matches regular files whose contents include content.
+// Directories never match.
+func FileContainsFilter(fsys fs.FS, content string) FilterFunc {
+	return func(pth string, d fs.DirEntry) (bool, error) {
+		if d != nil && d.IsDir() {
+			return false, nil
+		}
+		data, err := fs.ReadFile(fsys, pth)
+		if err != nil {
+			return false, err
+		}
+		return strings.Contains(string(data), content), nil
+	}
+}

pathutil/path_filter_compat.go

@@ -0,0 +1,84 @@
+package pathutil
+
+import (
+	"errors"
+	"io/fs"
+	"os"
+	"path/filepath"
+)
+
+// FilterPaths applies filters to an explicit list of OS paths and returns
+// the ones that pass every filter, preserving input order. Each path is
+// stat-ed to build an fs.DirEntry for the filter callbacks; a missing path
+// surfaces the stat error.
+//
+// This adapter preserves the v1 go-utils pathutil.FilterPaths signature so
+// callers can migrate by import-path rename only. Prefer FilterFS in new code.
+func FilterPaths(paths []string, filters ...FilterFunc) ([]string, error) {
+	var filtered []string
+	for _, pth := range paths {
+		info, err := os.Lstat(pth)
+		if err != nil {
+			return nil, err
+		}
+		d := fs.FileInfoToDirEntry(info)
+
+		keep, err := runFilters(pth, d, filters)
+		if err != nil {
+			return nil, err
+		}
+		if keep {
+			filtered = append(filtered, pth)
+		}
+	}
+	return filtered, nil
+}
+
+// ListEntries lists the immediate children of dir, applies filters, and
+// returns the matching entries as absolute paths. It is non-recursive.
+//
+// This adapter preserves the v1 go-utils pathutil.ListEntries signature so
+// callers can migrate by import-path rename only. Prefer FilterFS on an
+// fs.FS in new code.
+func ListEntries(dir string, filters ...FilterFunc) ([]string, error) {
+	absDir, err := filepath.Abs(dir)
+	if err != nil {
+		return nil, err
+	}
+	entries, err := os.ReadDir(absDir)
+	if err != nil {
+		return nil, err
+	}
+
+	var filtered []string
+	for _, entry := range entries {
+		pth := filepath.Join(absDir, entry.Name())
+		keep, err := runFilters(pth, entry, filters)
+		if err != nil {
+			return nil, err
+		}
+		if keep {
+			filtered = append(filtered, pth)
+		}
+	}
+	return filtered, nil
+}
+
+// runFilters evaluates filters in order. fs.SkipDir from a filter is
+// treated as "exclude this entry" rather than a walk directive, because the
+// compat adapters do not walk a tree.
+func runFilters(pth string, d fs.DirEntry, filters []FilterFunc) (bool, error) {
+	for _, filter := range filters {
+		matches, err := filter(pth, d)
+		if err != nil {
+			if errors.Is(err, fs.SkipDir) {
+				return false, nil
+			}
+			return false, err
+		}
+		if !matches {
+			return false, nil
+		}
+	}
+	return true, nil
+}

pathutil/path_filter_compat_test.go

@@ -0,0 +1,81 @@
+package pathutil
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+)
+
+func writeTempTree(t *testing.T) string {
+	t.Helper()
+
+	root := t.TempDir()
+
+	files := map[string]string{
+		"README.md":            "# readme",
+		"main.go":              "package main",
+		"main_test.go":         "package main",
+		"sub/note.txt":         "todo",
+		"sub/nested/deep.txt":  "x",
+		"vendor/pkg/lib.go":    "package pkg",
+	}
+	for rel, content := range files {
+		full := filepath.Join(root, rel)
+		require.NoError(t, os.MkdirAll(filepath.Dir(full), 0o755))
+		require.NoError(t, os.WriteFile(full, []byte(content), 0o644))
+	}
+	return root
+}
+
+func TestFilterPaths(t *testing.T) {
+	root := writeTempTree(t)
+	paths := []string{
+		filepath.Join(root, "README.md"),
+		filepath.Join(root, "main.go"),
+		filepath.Join(root, "main_test.go"),
+		filepath.Join(root, "sub"),
+	}
+
+	got, err := FilterPaths(paths, ExtensionFilter(".go", true), IsDirectoryFilter(false))
+	require.NoError(t, err)
+	require.ElementsMatch(t, []string{
+		filepath.Join(root, "main.go"),
+		filepath.Join(root, "main_test.go"),
+	}, got)
+}
+
+func TestFilterPaths_missingPathErrors(t *testing.T) {
+	_, err := FilterPaths([]string{"/does/not/exist/ever"}, IsDirectoryFilter(false))
+	require.Error(t, err)
+}
+
+func TestFilterPaths_empty(t *testing.T) {
+	got, err := FilterPaths(nil, ExtensionFilter(".go", true))
+	require.NoError(t, err)
+	require.Empty(t, got)
+}
+
+func TestListEntries(t *testing.T) {
+	root := writeTempTree(t)
+
+	got, err := ListEntries(root, IsDirectoryFilter(false))
+	require.NoError(t, err)
+	require.ElementsMatch(t, []string{
+		filepath.Join(root, "README.md"),
+		filepath.Join(root, "main.go"),
+		filepath.Join(root, "main_test.go"),
+	}, got, "ListEntries must be non-recursive")
+}
+
+func TestListEntries_onlyDirs(t *testing.T) {
+	root := writeTempTree(t)
+
+	got, err := ListEntries(root, IsDirectoryFilter(true))
+	require.NoError(t, err)
+	require.ElementsMatch(t, []string{
+		filepath.Join(root, "sub"),
+		filepath.Join(root, "vendor"),
+	}, got)
+}