Rationalize default configuration file paths and update documentation

internal/cli/run.go

@@ -982,13 +982,15 @@ func findConfigPathOverride(args []string) (path string, set bool, err error) {
 	return "", false, nil
 }
 
+var statConfigPath = os.Stat
+
 func resolveConfigPath(cliConfigPath string, cliConfigPathSet bool, lookup func(string) (string, bool)) (path string, source string, err error) {
 	if cliConfigPathSet {
 		path = strings.TrimSpace(cliConfigPath)
 		if path == "" {
 			return "", "", fmt.Errorf("--config requires a non-empty path")
 		}
-		if _, statErr := os.Stat(path); statErr != nil {
+		if _, statErr := statConfigPath(path); statErr != nil {
 			if os.IsNotExist(statErr) {
 				return "", "", fmt.Errorf("config file not found: %s", path)
 			}
@@ -1002,7 +1004,7 @@ func resolveConfigPath(cliConfigPath string, cliConfigPathSet bool, lookup func(
 		if path == "" {
 			return "", "", fmt.Errorf("AUDITA_CONFIG must not be empty")
 		}
-		if _, statErr := os.Stat(path); statErr != nil {
+		if _, statErr := statConfigPath(path); statErr != nil {
 			if os.IsNotExist(statErr) {
 				return "", "", fmt.Errorf("config file not found: %s", path)
 			}
@@ -1011,11 +1013,12 @@ func resolveConfigPath(cliConfigPath string, cliConfigPathSet bool, lookup func(
 		return path, "env", nil
 	}
 
-	defaultPath := config.DefaultConfigPath
-	if _, statErr := os.Stat(defaultPath); statErr == nil {
-		return defaultPath, "default", nil
-	} else if !os.IsNotExist(statErr) {
-		return "", "", fmt.Errorf("cannot access config file %s: %w", defaultPath, statErr)
+	for _, defaultPath := range config.DefaultConfigSearchPaths {
+		if _, statErr := statConfigPath(defaultPath); statErr == nil {
+			return defaultPath, "default", nil
+		} else if !os.IsNotExist(statErr) {
+			return "", "", fmt.Errorf("cannot access config file %s: %w", defaultPath, statErr)
+		}
 	}
 	return "", "", nil
 }

internal/cli/run_test.go

@@ -110,6 +110,55 @@ func TestResolveConfigPathDefaultIgnoredWhenMissing(t *testing.T) {
 	}
 }
 
+func TestResolveConfigPathDefaultPrefersUsrLocalOverEtc(t *testing.T) {
+	oldStat := statConfigPath
+	statConfigPath = func(path string) (os.FileInfo, error) {
+		if path == config.DefaultConfigPathUsrLocal || path == config.DefaultConfigPath {
+			return nil, nil
+		}
+		return nil, os.ErrNotExist
+	}
+	t.Cleanup(func() { statConfigPath = oldStat })
+
+	lookup := func(string) (string, bool) { return "", false }
+	path, source, err := resolveConfigPath("", false, lookup)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if source != "default" {
+		t.Fatalf("expected default source, got %q", source)
+	}
+	if path != config.DefaultConfigPathUsrLocal {
+		t.Fatalf("expected %q, got %q", config.DefaultConfigPathUsrLocal, path)
+	}
+}
+
+func TestResolveConfigPathDefaultFallsBackToEtc(t *testing.T) {
+	oldStat := statConfigPath
+	statConfigPath = func(path string) (os.FileInfo, error) {
+		if path == config.DefaultConfigPathUsrLocal {
+			return nil, os.ErrNotExist
+		}
+		if path == config.DefaultConfigPath {
+			return nil, nil
+		}
+		return nil, os.ErrNotExist
+	}
+	t.Cleanup(func() { statConfigPath = oldStat })
+
+	lookup := func(string) (string, bool) { return "", false }
+	path, source, err := resolveConfigPath("", false, lookup)
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if source != "default" {
+		t.Fatalf("expected default source, got %q", source)
+	}
+	if path != config.DefaultConfigPath {
+		t.Fatalf("expected %q, got %q", config.DefaultConfigPath, path)
+	}
+}
+
 func TestRunConfigValidateSuccess(t *testing.T) {
 	var stdout bytes.Buffer
 	var stderr bytes.Buffer