refactor(provider): expose LookupAlias/EachAlias accessors for the alias table

The Aliases map is package-level mutable global state. External consumers (pkg/config/gather.go, pkg/runtime/model_switcher.go) reach into the map directly, and tests that need to assert what happens when an alias has only a BaseURL or only a TokenEnvVar have to either pick whatever the live table happens to contain or risk corrupting global state for parallel tests.

Introduce two accessors that hide the storage detail:

  - LookupAlias(name) (Alias, bool) — single lookup, replaces all uses of Aliases[name].

  - EachAlias() iter.Seq2[string, Alias] — Go 1.23 iterator for ranging.

Migrate every external call site (gather.go, model_switcher.go) and all in-package usage outside provider.go to the accessors. The Aliases var stays exported for backwards compatibility but its godoc now points readers at the accessors and notes that direct mutation is unsupported.

Add unit tests that lock in the contracts (LookupAlias case-sensitivity and zero-value miss semantics, EachAlias completeness and early-termination via break).

Behaviour is unchanged. Both new accessors at 100% coverage; package coverage 96.4% -> 96.5%.

Assisted-By: docker-agent

Author: dgageot

pkg/config/gather.go

@@ -106,7 +106,7 @@ func addEnvVarsForModelConfig(model *latest.ModelConfig, customProviders map[str
 				addEnvVarsForCoreProvider(effective, model, requiredEnv)
 			}
 		}
-	} else if alias, exists := provider.Aliases[model.Provider]; exists {
+	} else if alias, exists := provider.LookupAlias(model.Provider); exists {
 		// Check built-in aliases
 		if alias.TokenEnvVar != "" {
 			requiredEnv[alias.TokenEnvVar] = true

pkg/model/provider/aliases_test.go

@@ -0,0 +1,54 @@
+package provider
+
+import (
+	"maps"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+func TestLookupAlias(t *testing.T) {
+	t.Parallel()
+
+	// Every entry in the table is reachable.
+	for name, expected := range Aliases {
+		got, ok := LookupAlias(name)
+		assert.True(t, ok, "alias %q should be found", name)
+		assert.Equal(t, expected, got)
+	}
+
+	// Unknown name yields the zero Alias and false.
+	got, ok := LookupAlias("does-not-exist")
+	assert.False(t, ok)
+	assert.Equal(t, Alias{}, got)
+
+	// Lookup is case-sensitive (callers normalise themselves).
+	if _, ok := LookupAlias("MISTRAL"); ok {
+		t.Errorf("LookupAlias should be case-sensitive")
+	}
+}
+
+func TestEachAlias(t *testing.T) {
+	t.Parallel()
+
+	// Iterator yields every entry exactly once.
+	collected := maps.Collect(EachAlias())
+	assert.Equal(t, Aliases, collected)
+}
+
+func TestEachAlias_EarlyTermination(t *testing.T) {
+	t.Parallel()
+
+	// Iterator must respect a false return from the yield function.
+	require.NotEmpty(t, Aliases, "test requires the alias table to be non-empty")
+
+	count := 0
+	for range EachAlias() {
+		count++
+		if count == 1 {
+			break
+		}
+	}
+	assert.Equal(t, 1, count, "iteration should stop when consumer breaks out")
+}

pkg/model/provider/provider.go

@@ -3,6 +3,7 @@ package provider
 import (
 	"context"
 	"fmt"
+	"iter"
 	"log/slog"
 	"maps"
 	"slices"
@@ -54,7 +55,7 @@ func IsKnownProvider(name string) bool {
 	if slices.Contains(CoreProviders, strings.ToLower(name)) {
 		return true
 	}
-	_, exists := Aliases[strings.ToLower(name)]
+	_, exists := LookupAlias(strings.ToLower(name))
 	return exists
 }
 
@@ -68,7 +69,7 @@ func CatalogProviders() []string {
 	providers = append(providers, CoreProviders...)
 
 	// Add aliases that have a defined BaseURL (they work out of the box)
-	for name, alias := range Aliases {
+	for name, alias := range EachAlias() {
 		if alias.BaseURL != "" {
 			providers = append(providers, name)
 		}
@@ -84,13 +85,17 @@ func IsCatalogProvider(name string) bool {
 		return true
 	}
 	// Check aliases with BaseURL
-	if alias, exists := Aliases[name]; exists && alias.BaseURL != "" {
+	if alias, exists := LookupAlias(name); exists && alias.BaseURL != "" {
 		return true
 	}
 	return false
 }
 
-// Aliases maps provider names to their corresponding configurations
+// Aliases maps provider names to their corresponding configurations.
+//
+// Most consumers should call [LookupAlias] for a single lookup or [EachAlias]
+// to iterate, both of which keep the rest of the codebase decoupled from this
+// concrete map. Direct mutation of Aliases is not supported.
 var Aliases = map[string]Alias{
 	"requesty": {
 		APIType:     "openai",
@@ -132,6 +137,27 @@ var Aliases = map[string]Alias{
 	},
 }
 
+// LookupAlias returns the Alias registered for the given name (if any).
+// Lookup is case-sensitive; callers that need case-insensitive matching
+// should normalise the name first (e.g. [strings.ToLower]).
+func LookupAlias(name string) (Alias, bool) {
+	alias, ok := Aliases[name]
+	return alias, ok
+}
+
+// EachAlias returns an iterator over every registered (name, Alias) pair.
+// Iteration order is not guaranteed; callers that need a deterministic order
+// should sort by name.
+func EachAlias() iter.Seq2[string, Alias] {
+	return func(yield func(string, Alias) bool) {
+		for name, alias := range Aliases {
+			if !yield(name, alias) {
+				return
+			}
+		}
+	}
+}
+
 // Provider defines the interface for model providers
 type Provider interface {
 	// ID returns the model provider ID
@@ -305,7 +331,7 @@ func resolveProviderType(cfg *latest.ModelConfig) string {
 			return apiType
 		}
 	}
-	if alias, exists := Aliases[cfg.Provider]; exists && alias.APIType != "" {
+	if alias, exists := LookupAlias(cfg.Provider); exists && alias.APIType != "" {
 		return alias.APIType
 	}
 	return cfg.Provider
@@ -337,7 +363,7 @@ func applyProviderDefaults(cfg *latest.ModelConfig, customProviders map[string]l
 		return enhancedCfg
 	}
 
-	if alias, exists := Aliases[cfg.Provider]; exists {
+	if alias, exists := LookupAlias(cfg.Provider); exists {
 		applyAliasFallbacks(enhancedCfg, alias)
 	}
 
@@ -571,7 +597,7 @@ func isOpenAICompatibleProvider(providerType string) bool {
 		return true
 	default:
 		// Check if it's an alias that maps to openai
-		if alias, exists := Aliases[providerType]; exists {
+		if alias, exists := LookupAlias(providerType); exists {
 			return alias.APIType == "openai"
 		}
 		return false

pkg/model/provider/provider_test.go

@@ -17,7 +17,7 @@ func TestCatalogProviders(t *testing.T) {
 	}
 
 	// Should include aliases with BaseURL
-	for name, alias := range Aliases {
+	for name, alias := range EachAlias() {
 		if alias.BaseURL != "" {
 			assert.Contains(t, providers, name, "should include alias %s with BaseURL", name)
 		} else {
@@ -35,7 +35,7 @@ func TestIsCatalogProvider(t *testing.T) {
 	}
 
 	// Aliases: catalog if and only if they have a BaseURL
-	for name, alias := range Aliases {
+	for name, alias := range EachAlias() {
 		if alias.BaseURL != "" {
 			assert.True(t, IsCatalogProvider(name), "alias %s with BaseURL should be a catalog provider", name)
 		} else {
@@ -59,7 +59,7 @@ func TestAllProviders(t *testing.T) {
 	}
 
 	// Should include all aliases
-	for name := range Aliases {
+	for name := range EachAlias() {
 		assert.Contains(t, all, name, "should include alias %s", name)
 	}
 
@@ -76,7 +76,7 @@ func TestIsKnownProvider(t *testing.T) {
 	}
 
 	// All aliases should be known
-	for name := range Aliases {
+	for name := range EachAlias() {
 		assert.True(t, IsKnownProvider(name), "alias %s should be known", name)
 	}
 

pkg/model/provider/resolve_test.go

@@ -54,7 +54,7 @@ func TestIsOpenAICompatibleProvider(t *testing.T) {
 	}
 
 	// Aliases that point to the openai api — the previously-uncovered tail.
-	for name, alias := range Aliases {
+	for name, alias := range EachAlias() {
 		if alias.APIType == "openai" {
 			t.Run("alias/"+name, func(t *testing.T) {
 				t.Parallel()

pkg/runtime/model_switcher.go

@@ -466,7 +466,7 @@ func (r *LocalRuntime) getAvailableProviders(ctx context.Context) map[string]boo
 	}
 
 	// Check credentials for each alias provider
-	for name, alias := range provider.Aliases {
+	for name, alias := range provider.EachAlias() {
 		if alias.TokenEnvVar == "" {
 			continue
 		}