fix: keep oasdiff.* lookup as back-compat fallback after .oasdiff.*

reuvenharrison · reuvenharrison · commit 020c051e8335 · 2026-05-09T00:40:12.000+03:00
The previous commit dropped the legacy oasdiff.{yaml,...} cwd lookup
entirely. That's a real backward-compatibility break: the lookup has
been live for a long time, and we don't know how many CLI users have
oasdiff.yaml committed to their working directories. Silently breaking
those users for the sake of strict convention isn't worth it when the
fix costs nothing.

Lookup order now (in cwd, first hit wins):

1. .oasdiff.{json,yaml,yml,toml,hcl} — preferred (dotfile convention)
2. oasdiff.{json,yaml,yml,toml,hcl}  — legacy fallback, no warning,
   no plan to remove

Existing oasdiff.* users don't have to do anything; .oasdiff.* is
recommended for new setups.

Tests: TestViper_DefaultLookup_LegacyOasdiffYamlIsIgnored renamed and
inverted to TestViper_DefaultLookup_LegacyOasdiffYamlStillWorks. New
TestViper_DefaultLookup_DotPreferredOverLegacy asserts the precedence
order when both files coexist.

CONFIG-FILES.md documents both filenames and the precedence.
diff --git a/docs/CONFIG-FILES.md b/docs/CONFIG-FILES.md
@@ -4,7 +4,12 @@ This is useful for complex configurations or repeated usage patterns.
 
 ## Default lookup
 
-By default, `oasdiff` looks for `.oasdiff.{json,yaml,yml,toml,hcl}` in the directory where the command is run.
+By default, `oasdiff` looks for a config file in the directory where the command is run, in this order:
+
+1. `.oasdiff.{json,yaml,yml,toml,hcl}` — preferred (dotfile convention)
+2. `oasdiff.{json,yaml,yml,toml,hcl}` — legacy fallback, kept for back-compat with existing setups
+
+`.oasdiff.*` is recommended for new setups. Existing `oasdiff.*` users don't need to migrate — both filenames continue to work.
 
 For example, see [.oasdiff.yaml](../examples/.oasdiff.yaml).
 
diff --git a/internal/viper.go b/internal/viper.go
@@ -48,7 +48,9 @@ func RunViper(cmd *cobra.Command, v IViper) *ReturnError {
 //
 //  1. --config <path> flag (when set, the file MUST exist; missing or malformed file is an error)
 //  2. OASDIFF_CONFIG environment variable (same semantics)
-//  3. Default cwd lookup for .oasdiff.{json,yaml,yml,toml,hcl} (silent when missing)
+//  3. Default cwd lookup, in order:
+//     a. .oasdiff.{json,yaml,yml,toml,hcl} (preferred — dotfile convention)
+//     b. oasdiff.{json,yaml,yml,toml,hcl} (legacy — kept for back-compat, still works without warning)
 //
 // Returns nil when no config is found via the default lookup; only the two
 // explicit-override paths surface "file not found" as an error.
@@ -61,18 +63,24 @@ func readConfFile(cmd *cobra.Command, v IViper) error {
 		return nil
 	}
 
-	// Default lookup: .oasdiff.{json,yaml,yml,toml,hcl} in cwd.
-	v.SetConfigName(".oasdiff")
-	v.AddConfigPath(".")
+	// Default lookup: try .oasdiff.* first (preferred), then oasdiff.*
+	// (legacy back-compat) — cwd-scoped, all viper-supported extensions.
+	for _, name := range []string{".oasdiff", "oasdiff"} {
+		v.SetConfigName(name)
+		v.AddConfigPath(".")
 
-	if err := v.ReadInConfig(); err != nil {
-		if _, ok := err.(viper.ConfigFileNotFoundError); ok {
-			// Config file not found; ignore error
-		} else {
-			return fmt.Errorf("read error: %s", err)
+		err := v.ReadInConfig()
+		if err == nil {
+			return nil
+		}
+		if _, notFound := err.(viper.ConfigFileNotFoundError); notFound {
+			continue // try the next candidate
 		}
+		// File found but malformed — surface the error.
+		return fmt.Errorf("read error: %s", err)
 	}
 
+	// No config file found in cwd; not an error.
 	return nil
 }
 
diff --git a/internal/viper_test.go b/internal/viper_test.go
@@ -205,18 +205,32 @@ func TestViper_DefaultLookup_DotOasdiffYaml(t *testing.T) {
 		"failed to load config file: invalid lang \"invalid\", allowed values: en, ru, pt-br, es")
 }
 
-// TestViper_DefaultLookup_LegacyOasdiffYamlIsIgnored: a legacy
-// oasdiff.yaml (no leading dot) at repo root is no longer recognized
-// by the default lookup. The CLI should silently skip it.
-func TestViper_DefaultLookup_LegacyOasdiffYamlIsIgnored(t *testing.T) {
+// TestViper_DefaultLookup_LegacyOasdiffYamlStillWorks: the legacy
+// oasdiff.{yaml,...} filename remains supported as a back-compat
+// fallback for CLI users who had it set up before the .oasdiff.* move.
+// .oasdiff.* is preferred, but oasdiff.* keeps working when no dotfile
+// is present.
+func TestViper_DefaultLookup_LegacyOasdiffYamlStillWorks(t *testing.T) {
 	chdirIsolated(t)
-	// Legacy filename — would have been picked up before the .oasdiff.*
-	// move. Now it should be ignored entirely.
 	writeFile(t, "oasdiff.yaml", "lang: invalid\n")
 
 	cmd := cobra.Command{}
-	// No error: validate() never sees the bad value because the file
-	// wasn't loaded.
+	require.EqualError(t,
+		internal.RunViper(&cmd, viper.New()),
+		"failed to load config file: invalid lang \"invalid\", allowed values: en, ru, pt-br, es")
+}
+
+// TestViper_DefaultLookup_DotPreferredOverLegacy: when both .oasdiff.yaml
+// and oasdiff.yaml exist in cwd, the dotfile wins. Proves the lookup
+// order — preferred first, legacy as fallback only.
+func TestViper_DefaultLookup_DotPreferredOverLegacy(t *testing.T) {
+	chdirIsolated(t)
+	// Dotfile is clean; legacy is not. If the legacy file were loaded,
+	// validate() would error.
+	writeFile(t, ".oasdiff.yaml", "lang: en\n")
+	writeFile(t, "oasdiff.yaml", "lang: invalid\n")
+
+	cmd := cobra.Command{}
 	require.Nil(t, internal.RunViper(&cmd, viper.New()))
 }
 
