Rationalize default configuration file paths and update documentation

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