fix: name the spelling a vocab term wants, not its pattern

Signed-off-by: Joseph Kato <joseph@jdkato.io>

Author: jdkato

internal/check/expand_bench_test.go

@@ -0,0 +1,19 @@
+package check
+
+import "testing"
+
+func BenchmarkRecaseToTerm(b *testing.B) {
+	for _, c := range []struct{ name, term, observed string }{
+		{"literal", "OpenAPI", "openapi"},
+		{"optional", "OAuth2?", "Oauth"},
+		{"alternation", "Docker(file|ize)", "dockerfile"},
+		{"bails", "[Pp]ython", "python"},
+	} {
+		b.Run(c.name, func(b *testing.B) {
+			b.ReportAllocs()
+			for i := 0; i < b.N; i++ {
+				_ = recaseToTerm(c.term, c.observed)
+			}
+		})
+	}
+}

internal/check/substitution.go

@@ -4,6 +4,8 @@ import (
 	"fmt"
 	"sort"
 	"strings"
+	"sync"
+	"unicode"
 
 	"golang.org/x/exp/maps"
 
@@ -237,17 +239,139 @@ func literalSkeleton(pattern string) string {
 	return b.String()
 }
 
-// recaseToTerm re-cases observed to a vocab term's canonical form when the term
-// is a regex describing a single fixed-length spelling (e.g. `OAuth2?` against
-// `oauth2` yields `OAuth2`). It returns term unchanged when the pattern can't
-// be cleanly aligned, so the raw regex is only ever shown as a last resort.
-// See #997.
+// Alternations multiply out fast; past a handful the term is no longer one
+// word spelled several ways.
+const maxExpansions = 64
+
+// expandPattern enumerates every spelling a vocab term can match -- `OAuth2?`
+// gives OAuth2 and OAuth -- or nil if the pattern is not a finite set.
+func expandPattern(pattern string) []string {
+	runes := []rune(pattern)
+
+	// parse reads an alternation at i, returning its spellings and the index
+	// just past what it consumed.
+	var parse func(i int, nested bool) (out []string, next int, ok bool)
+	parse = func(i int, nested bool) ([]string, int, bool) {
+		branches := []string{}  // completed alternatives
+		current := []string{""} // spellings of the branch being read
+
+		// cross appends every element of add to every spelling so far.
+		cross := func(add []string) bool {
+			if len(current)*len(add) > maxExpansions {
+				return false
+			}
+			next := make([]string, 0, len(current)*len(add))
+			for _, prefix := range current {
+				for _, suffix := range add {
+					next = append(next, prefix+suffix)
+				}
+			}
+			current = next
+			return true
+		}
+
+		for i < len(runes) {
+			var atom []string
+
+			switch r := runes[i]; r {
+			case ')':
+				if !nested {
+					return nil, 0, false // unbalanced
+				}
+				return append(branches, current...), i + 1, true
+			case '|':
+				branches = append(branches, current...)
+				current = []string{""}
+				i++
+				continue
+			case '(':
+				start := i + 1
+				// Capturing or not makes no difference to the spellings.
+				if strings.HasPrefix(string(runes[start:]), "?:") {
+					start += 2
+				} else if start < len(runes) && runes[start] == '?' {
+					return nil, 0, false // lookaround, named group, flags
+				}
+				inner, next, ok := parse(start, true)
+				if !ok {
+					return nil, 0, false
+				}
+				atom, i = inner, next
+			case '\\':
+				if i+1 >= len(runes) {
+					return nil, 0, false
+				}
+				// `\d`, `\w`, `\b` are not fixed spellings.
+				next := runes[i+1]
+				if unicode.IsLetter(next) || unicode.IsDigit(next) {
+					return nil, 0, false
+				}
+				atom = []string{string(next)}
+				i += 2
+			case '[', ']', '{', '}', '.', '*', '+', '^', '$':
+				return nil, 0, false
+			default:
+				atom = []string{string(r)}
+				i++
+			}
+
+			// `?` makes the atom optional: add the empty spelling too.
+			if i < len(runes) && runes[i] == '?' {
+				atom = append(append([]string{}, atom...), "")
+				i++
+			} else if i < len(runes) && (runes[i] == '*' || runes[i] == '+' || runes[i] == '{') {
+				return nil, 0, false
+			}
+
+			if !cross(atom) {
+				return nil, 0, false
+			}
+		}
+
+		if nested {
+			return nil, 0, false // unterminated group
+		}
+		return append(branches, current...), i, true
+	}
+
+	out, next, ok := parse(0, false)
+	if !ok || next != len(runes) || len(out) == 0 {
+		return nil
+	}
+
+	return out
+}
+
+// Computed once per term, not once per alert; a run can raise hundreds of
+// thousands against the same few terms.
+var expansions sync.Map // pattern -> []string
+
+func expansionsFor(term string) []string {
+	if cached, ok := expansions.Load(term); ok {
+		return cached.([]string)
+	}
+
+	out := expandPattern(term)
+	if out == nil {
+		if skel := literalSkeleton(term); skel != "" {
+			out = []string{skel}
+		}
+	}
+
+	expansions.Store(term, out)
+	return out
+}
+
+// recaseToTerm re-cases observed to a vocab term's canonical spelling, e.g.
+// `OAuth2?` against `Oauth` yields `OAuth`. It returns term unchanged when no
+// spelling matches, so the raw regex is only ever a last resort. See #997.
 func recaseToTerm(term, observed string) string {
-	skel := literalSkeleton(term)
-	if skel == "" || !strings.EqualFold(skel, observed) {
-		return term
+	for _, candidate := range expansionsFor(term) {
+		if strings.EqualFold(candidate, observed) {
+			return candidate
+		}
 	}
-	return skel
+	return term
 }
 
 func convertMessage(s string) string {

internal/check/substitution_test.go

@@ -1,6 +1,9 @@
 package check
 
 import (
+	"slices"
+	"sort"
+	"strings"
 	"testing"
 
 	"github.com/errata-ai/vale/v3/internal/core"
@@ -164,12 +167,22 @@ func TestRecaseToTerm(t *testing.T) {
 	cases := []struct {
 		term, observed, want string
 	}{
-		{"OAuth2?", "oauth2", "OAuth2"},       // optional char present
-		{"OpenAPI", "openapi", "OpenAPI"},     // plain literal
-		{`Wi\-?Fi`, "wi-fi", "Wi-Fi"},         // escaped literal hyphen, aligned
-		{"Wi-?Fi", "wifi", "Wi-?Fi"},          // optional char absent -> fall back
-		{"[Pp]ython", "python", "[Pp]ython"},  // class -> fall back
-		{"(?:foo|bar)", "foo", "(?:foo|bar)"}, // group/alternation -> fall back
+		{"OAuth2?", "oauth2", "OAuth2"},                  // optional char present
+		{"OAuth2?", "Oauth", "OAuth"},                    // optional char absent -- see #997
+		{"OpenAPI", "openapi", "OpenAPI"},                // plain literal
+		{`Wi\-?Fi`, "wi-fi", "Wi-Fi"},                    // escaped literal hyphen
+		{"Wi-?Fi", "wifi", "WiFi"},                       // optional char absent
+		{"Docker(file|ize)", "dockerfile", "Dockerfile"}, // alternation -- see #997
+		{"Docker(file|ize)", "DOCKERIZE", "Dockerize"},
+		{"(?:foo|bar)", "foo", "foo"}, // non-capturing group
+
+		// No spelling in the set matches, so the term stands.
+		{"Docker(file|ize)", "docker", "Docker(file|ize)"},
+
+		// Not a finite set of spellings: nothing to name.
+		{"[Pp]ython", "python", "[Pp]ython"},
+		{`Py.*\b`, "pythonic", `Py.*\b`},
+		{"Go+gle", "google", "Go+gle"},
 	}
 	for _, c := range cases {
 		if got := recaseToTerm(c.term, c.observed); got != c.want {
@@ -178,6 +191,67 @@ func TestRecaseToTerm(t *testing.T) {
 	}
 }
 
+func TestExpandPattern(t *testing.T) {
+	cases := []struct {
+		pattern string
+		want    []string
+	}{
+		{"OAuth", []string{"OAuth"}},
+		{"OAuth2?", []string{"OAuth2", "OAuth"}},
+		{"Docker(file|ize)", []string{"Dockerfile", "Dockerize"}},
+		{"Docker(?:file|ize)", []string{"Dockerfile", "Dockerize"}},
+		{"foo|bar", []string{"foo", "bar"}},
+		{`Wi\-Fi`, []string{"Wi-Fi"}},
+		{"a(b|c)d?", []string{"abd", "ab", "acd", "ac"}},
+
+		// Optional group: the whole group drops out.
+		{"Java(Script)?", []string{"JavaScript", "Java"}},
+
+		// Unbounded or class-based -- no finite set of spellings.
+		{"[Pp]ython", nil},
+		{"Go+gle", nil},
+		{"Py.*", nil},
+		{`\d+`, nil},
+		{"a{2,3}", nil},
+		{"(unclosed", nil},
+		{"unopened)", nil},
+		{"(?=lookahead)", nil},
+	}
+
+	for _, c := range cases {
+		got := expandPattern(c.pattern)
+		if c.want == nil {
+			if got != nil {
+				t.Errorf("expandPattern(%q) = %v, want nil", c.pattern, got)
+			}
+			continue
+		}
+		if !slices.Equal(sorted(got), sorted(c.want)) {
+			t.Errorf("expandPattern(%q) = %v, want %v", c.pattern, got, c.want)
+		}
+	}
+}
+
+// A blown budget has to return nil rather than a truncated set: a partial list
+// would let recaseToTerm miss the spelling the writer actually used and report
+// the raw pattern, which is the bug this exists to avoid.
+func TestExpandPatternBudget(t *testing.T) {
+	// 2^7 = 128 spellings, past maxExpansions.
+	if got := expandPattern(strings.Repeat("(a|b)", 7)); got != nil {
+		t.Errorf("expected nil past the budget, got %d spellings", len(got))
+	}
+	// 2^5 = 32, inside it.
+	if got := expandPattern(strings.Repeat("(a|b)", 5)); len(got) != 32 {
+		t.Errorf("expected 32 spellings, got %d", len(got))
+	}
+}
+
+func sorted(s []string) []string {
+	out := append([]string{}, s...)
+	sort.Strings(out)
+	return out
+}
+
 func TestOptions(t *testing.T) {
 	cases := map[string][]string{
 		"foo|bar":     {"foo", "bar"},