Improve registry filter options naming (#58)

peteski22 · web-flow · commit 219caf62302a · 2025-07-02T19:42:34.000+01:00
* Improve registry filter options naming

* Update --tag and --category to use partial matches
diff --git a/internal/filter/match.go b/internal/filter/match.go
@@ -61,10 +61,19 @@ func NewOptions[T any](opt ...Option[T]) (Options[T], error) {
 	return opts, nil
 }
 
+// ValueProvider extracts a single string value from an item of type T.
 type ValueProvider[T any] func(T) string
 
+// ValuesProvider extracts a slice of string values from an item of type T.
 type ValuesProvider[T any] func(T) []string
 
+// Equals returns a Predicate that checks if the value extracted by the provider
+// exactly matches the filter value (case-insensitive, normalized).
+//
+// Example:
+//
+// predicate := Equals(options.SourceProvider),
+// result := predicate(pkg, "github") // true if pkg.Source equals "github"
 func Equals[T any](provider ValueProvider[T]) Predicate[T] {
 	return func(item T, val string) bool {
 		actual := NormalizeString(provider(item))
@@ -73,18 +82,84 @@ func Equals[T any](provider ValueProvider[T]) Predicate[T] {
 	}
 }
 
-func Contains[T any](provider ValueProvider[T]) Predicate[T] {
+// Partial returns a Predicate that checks if the value extracted by the provider
+// contains the filter value as a substring (case-insensitive, normalized).
+//
+// Example:
+//
+// predicate := Partial(options.VersionProvider),
+// result := predicate(pkg, "1.2") // true if pkg.Version contains "1.2"
+func Partial[T any](provider ValueProvider[T]) Predicate[T] {
 	return func(item T, val string) bool {
 		actual := NormalizeString(provider(item))
 		expected := NormalizeString(val)
 		return strings.Contains(actual, expected)
 	}
 }
 
-func ContainsOnly[T any](provider ValuesProvider[T]) Predicate[T] {
+// PartialAll returns a Predicate that checks if *ALL* comma-separated values in the filter string are found
+// as substrings within provided values (case-insensitive, normalized).
+// Functionally similar to Partial, but operates on a ValuesProvider, and expects the filter to be comma-separated.
+//
+// Example:
+//
+// predicate := PartialAll(options.ToolsProvider),
+// result := predicate(pkg, "get_current_time,convert_time") // true if pkg.Tools contains values with "get_current_time" and "convert_time" as substrings
+func PartialAll[T any](provider ValuesProvider[T]) Predicate[T] {
+	return func(item T, val string) bool {
+		required := NormalizeSlice(strings.Split(val, ","))
+		actual := NormalizeSlice(provider(item))
+
+		for _, v := range required {
+			found := false
+			for _, a := range actual {
+				if strings.Contains(a, v) {
+					found = true
+					break
+				}
+			}
+			if !found {
+				return false
+			}
+		}
+		return true
+	}
+}
+
+// EqualsAny returns a Predicate that checks if *ANY* of the values from the supplied providers are equal to the
+// filter value (case-insensitive, normalized).
+// Functionally similar to Equals, but operates on one or more ValueProvider.
+//
+// Example:
+//
+// predicate := EqualsAny(options.ToolsProvider),
+// result := predicate(pkg, "get_current_time,convert_time") // true if pkg.Tools contains values "get_current_time" or "convert_time"
+func EqualsAny[T any](providers ...ValueProvider[T]) Predicate[T] {
+	return func(item T, val string) bool {
+		q := NormalizeString(val)
+		for _, p := range providers {
+			actual := NormalizeString(p(item))
+			if strings.Contains(actual, q) {
+				return true
+			}
+		}
+		return false
+	}
+}
+
+// HasOnly returns a Predicate that checks if the values extracted by the provider are a subset of
+// the comma-separated values in the filter string (case-insensitive, normalized).
+// Returns true only if *ALL* extracted values are present in the filter list.
+//
+// Example:
+//
+// predicate := HasOnly(options.ToolsProvider),
+// result := predicate(pkg, "get_current_time,convert_time") // true if pkg.Tools only contains tools from the list
+func HasOnly[T any](provider ValuesProvider[T]) Predicate[T] {
 	return func(item T, val string) bool {
 		required := strings.Split(val, ",")
 		expected := make(map[string]struct{}, len(required))
+
 		for _, v := range required {
 			expected[NormalizeString(v)] = struct{}{}
 		}
@@ -98,31 +173,48 @@ func ContainsOnly[T any](provider ValuesProvider[T]) Predicate[T] {
 	}
 }
 
-func ContainsAll[T any](provider ValuesProvider[T]) Predicate[T] {
+// HasAll returns a Predicate that checks if the values extracted by the provider include *ALL*
+// of the comma-separated values in the filter string (case-insensitive, normalized)..
+// Returns true only if *ALL* required values are present in the extracted values.
+//
+// Example:
+//
+// predicate := HasAll(options.ToolsProvider),
+// result := predicate(pkg, "get_current_time,convert_time") // true if pkg.Tools contains both "get_current_time" and "convert_time"
+func HasAll[T any](provider ValuesProvider[T]) Predicate[T] {
 	return func(item T, val string) bool {
 		required := NormalizeSlice(strings.Split(val, ","))
 		actual := provider(item)
+		allowed := make(map[string]struct{}, len(actual))
 
-		actualSet := make(map[string]struct{}, len(actual))
 		for _, v := range actual {
-			actualSet[NormalizeString(v)] = struct{}{}
+			allowed[NormalizeString(v)] = struct{}{}
 		}
 
 		for _, r := range required {
-			if _, ok := actualSet[r]; !ok {
+			if _, ok := allowed[r]; !ok {
 				return false
 			}
 		}
 		return true
 	}
 }
 
-func ContainsAny[T any](provider ValuesProvider[T]) Predicate[T] {
+// HasAny returns a Predicate that checks if the values extracted by the provider include *ANY* of
+// the comma-separated values in the filter string (case-insensitive, normalized).
+// Returns true if at least one required value is present in the extracted values.
+//
+// Example:
+//
+// predicate := HasAny(options.ToolsProvider),
+// result := predicate(pkg, "get_current_time,convert_time") // true if pkg.Tools contains either "get_current_time" or "convert_time"
+func HasAny[T any](provider ValuesProvider[T]) Predicate[T] {
 	return func(item T, val string) bool {
-		required := strings.Split(val, ",")
+		required := NormalizeSlice(strings.Split(val, ","))
 		allowed := make(map[string]struct{}, len(required))
+
 		for _, v := range required {
-			allowed[NormalizeString(v)] = struct{}{}
+			allowed[v] = struct{}{}
 		}
 
 		for _, v := range provider(item) {
@@ -134,19 +226,6 @@ func ContainsAny[T any](provider ValuesProvider[T]) Predicate[T] {
 	}
 }
 
-func OrContains[T any](providers ...ValueProvider[T]) Predicate[T] {
-	return func(item T, val string) bool {
-		q := NormalizeString(val)
-		for _, p := range providers {
-			actual := NormalizeString(p(item))
-			if strings.Contains(actual, q) {
-				return true
-			}
-		}
-		return false
-	}
-}
-
 // WithMatchers adds or overrides matchers.
 func WithMatchers[T any](m map[string]Predicate[T]) Option[T] {
 	return func(o *Options[T]) error {
diff --git a/internal/filter/match_test.go b/internal/filter/match_test.go
@@ -32,31 +32,41 @@ func TestEquals(t *testing.T) {
 }
 
 func TestContains(t *testing.T) {
-	p := Contains(func(m testItem) string { return m.Category })
+	p := Partial(func(m testItem) string { return m.Category })
 	assert.True(t, p(testItem{Category: "devtools"}, "tool"))
 	assert.False(t, p(testItem{Category: "runtime"}, "tool"))
 }
 
-func TestContainsOnly(t *testing.T) {
-	p := ContainsOnly(func(m testItem) []string { return m.Tags })
+func TestHasOnly(t *testing.T) {
+	p := HasOnly(func(m testItem) []string { return m.Tags })
 	assert.True(t, p(testItem{Tags: []string{"A", "B"}}, "a,b"))
 	assert.False(t, p(testItem{Tags: []string{"A", "C"}}, "a,b"))
 }
 
-func TestContainsAll(t *testing.T) {
-	p := ContainsAll(func(m testItem) []string { return m.Tags })
+func TestHasAll(t *testing.T) {
+	p := HasAll(func(m testItem) []string { return m.Tags })
 	assert.True(t, p(testItem{Tags: []string{"X", "Y", "Z"}}, "x,y"))
 	assert.False(t, p(testItem{Tags: []string{"X", "Y"}}, "x,y,z"))
 }
 
-func TestContainsAny(t *testing.T) {
-	p := ContainsAny(func(m testItem) []string { return m.Tags })
+func TestHasAny(t *testing.T) {
+	p := HasAny(func(m testItem) []string { return m.Tags })
 	assert.True(t, p(testItem{Tags: []string{"alpha", "beta"}}, "beta,gamma"))
 	assert.False(t, p(testItem{Tags: []string{"alpha"}}, "beta,gamma"))
 }
 
-func TestOrContains(t *testing.T) {
-	p := OrContains(
+func TestPartialAll(t *testing.T) {
+	p := PartialAll(func(m testItem) []string { return m.Tags })
+	// foo is a substring of foo2, bar is a substring of bar3, so both (all) match.
+	assert.True(t, p(testItem{Name: "a", Tags: []string{"foo2", "bar3"}}, "foo,bar"))
+	// foo is a substring of foo2, filter was only a single value so all have matched.
+	assert.True(t, p(testItem{Name: "a", Tags: []string{"foo2", "bar3"}}, "foo"))
+	// foo doesn't match any of the values even as substrings.
+	assert.False(t, p(testItem{Name: "b", Tags: []string{"baz", "bar"}}, "foo"))
+}
+
+func TestEqualsAny(t *testing.T) {
+	p := EqualsAny(
 		func(m testItem) string { return m.Name },
 		func(m testItem) string { return m.Category },
 	)
diff --git a/internal/registry/options/filter.go b/internal/registry/options/filter.go
@@ -107,31 +107,31 @@ func WithNameMatcher() Option {
 // The matcher is applied during Match only if the runtime filter key is present in the filters map.
 // Matching is case-insensitive and uses normalized values.
 func WithRuntimeMatcher(provider ValuesProvider) Option {
-	return filter.WithMatcher(FilterKeyRuntime, filter.ContainsAny(provider))
+	return filter.WithMatcher(FilterKeyRuntime, filter.HasAny(provider))
 }
 
 // WithToolsMatcher returns a filter.Option with a matcher configured for the "tools" filter key.
 // The matcher is applied during Match only if the tools filter key is present in the filters map.
 // This matcher returns true only if all filter values are found in the package's tools.
 // Matching is case-insensitive and uses normalized values.
 func WithToolsMatcher(provider ValuesProvider) Option {
-	return filter.WithMatcher(FilterKeyTools, filter.ContainsAll(provider))
+	return filter.WithMatcher(FilterKeyTools, filter.HasAll(provider))
 }
 
 // WithTagsMatcher returns a filter.Option with a matcher configured for the "tags" filter key.
 // The matcher is applied during Match only if the tags filter key is present in the filters map.
-// This matcher returns true if all of the filter values are found in the package's tags.
+// This matcher returns true if all the filter values are found in the package's tag as substrings.
 // Matching is case-insensitive and uses normalized values.
 func WithTagsMatcher(provider ValuesProvider) Option {
-	return filter.WithMatcher(FilterKeyTags, filter.ContainsAll(provider))
+	return filter.WithMatcher(FilterKeyTags, filter.PartialAll(provider))
 }
 
 // WithCategoriesMatcher returns a filter.Option with a matcher configured for the "categories" filter key.
 // The matcher is applied during Match only if the categories filter key is present in the filters map.
-// This matcher returns true if all of the filter values are found in the package's categories.
+// This matcher returns true if all the filter values are found in the package's categories as substrings.
 // Matching is case-insensitive and uses normalized values.
 func WithCategoriesMatcher(provider ValuesProvider) Option {
-	return filter.WithMatcher(FilterKeyCategories, filter.ContainsAll(provider))
+	return filter.WithMatcher(FilterKeyCategories, filter.PartialAll(provider))
 }
 
 // WithVersionMatcher returns a filter.Option with a matcher configured for the "version" filter key.
@@ -145,7 +145,7 @@ func WithVersionMatcher(provider ValueProvider) Option {
 // The matcher is applied during Match only if the license filter key is present in the filters map.
 // This matcher performs case-insensitive substring matching on the license field.
 func WithLicenseMatcher(provider ValueProvider) Option {
-	return filter.WithMatcher(FilterKeyLicense, filter.Contains(provider))
+	return filter.WithMatcher(FilterKeyLicense, filter.Partial(provider))
 }
 
 // WithSourceMatcher returns a filter.Option with a matcher configured for the "source" filter key.
@@ -167,19 +167,19 @@ func withWildcardMatcher(providers ...ValueProvider) Predicate {
 		if q == WildcardCharacter {
 			return true
 		}
-		return filter.OrContains(providers...)(pkg, q)
+		return filter.EqualsAny(providers...)(pkg, q)
 	}
 }
 
 func DefaultMatchers() map[string]Predicate {
 	return map[string]Predicate{
 		FilterKeyName:       withWildcardMatcher(NameProvider, DisplayNameProvider, IDProvider),
-		FilterKeyRuntime:    filter.ContainsAny(RuntimesProvider),
-		FilterKeyTools:      filter.ContainsAll(ToolsProvider),
-		FilterKeyTags:       filter.ContainsAll(TagsProvider),
-		FilterKeyCategories: filter.ContainsAll(CategoriesProvider),
+		FilterKeyRuntime:    filter.HasAny(RuntimesProvider),
+		FilterKeyTools:      filter.HasAll(ToolsProvider),
+		FilterKeyTags:       filter.PartialAll(TagsProvider),
+		FilterKeyCategories: filter.PartialAll(CategoriesProvider),
 		FilterKeyVersion:    filter.Equals(VersionProvider),
-		FilterKeyLicense:    filter.Contains(LicenseProvider),
+		FilterKeyLicense:    filter.Partial(LicenseProvider),
 		FilterKeySource:     filter.Equals(SourceProvider),
 	}
 }
