Summary

Adds .oasdiff.{json,yaml,yml,toml,hcl} as the preferred default config-file location, keeps the existing oasdiff.{json,yaml,yml,toml,hcl} lookup as a back-compat fallback, and adds two override mechanisms: a --config <path> persistent flag on the root command and an OASDIFF_CONFIG environment variable.

Why add .oasdiff.*

The dotfile convention is the overwhelming pattern for CI/lint tools — .eslintrc, .prettierrc, .golangci.yml, .yamllint, .flake8, .markdownlint.json, etc. The original oasdiff.{yaml,...} at the repo root reads as a project-defining file (Cargo.toml, package.json, pyproject.toml), which oasdiff isn't — it's a tool that operates on a project, not part of one. .oasdiff.* aligns with community muscle memory and makes the file's role obvious at a glance.

Why keep oasdiff.* as a fallback

The legacy lookup has been live in the CLI for a long time. We don't know how many users have oasdiff.yaml committed to their working directories. Silently breaking them for the sake of strict convention isn't worth it when the cost of keeping both is one extra SetConfigName call. Existing users don't have to do anything; .oasdiff.* is recommended for new setups.

Lookup order

In cwd, first hit wins:

1. .oasdiff.{json,yaml,yml,toml,hcl} — preferred (dotfile)
2. oasdiff.{json,yaml,yml,toml,hcl} — legacy fallback

Plus two explicit overrides that bypass the cwd lookup entirely:

• --config <path> (persistent flag on root, inherited by all subcommands)
• OASDIFF_CONFIG environment variable

Override precedence: --config <path> > OASDIFF_CONFIG > default cwd lookup.

When either override is set, the file MUST exist — missing or malformed file is an explicit error. The default cwd lookup retains its silent-skip semantics.

Why the env var (not just the flag)

The env var earns its place specifically for CI workflows: a customer with multiple oasdiff invocations in one workflow sets OASDIFF_CONFIG once at the workflow's env: block instead of duplicating --config per step. This matches industry convention (KUBECONFIG, AWS_CONFIG_FILE, DOCKER_CONFIG, NPM_CONFIG_USERCONFIG).

What's in the diff

• internal/viper.go — readConfFile checks the override sources in order, falls back to a two-candidate cwd lookup (.oasdiff then oasdiff). New EnvConfigPath constant for the env var name. IViper interface gains SetConfigFile (already on viper.Viper, so no mock changes needed).
• internal/run.go — --config added as a persistent flag on the root command.
• internal/viper_test.go — 8 new tests covering: .oasdiff.yaml loaded; legacy oasdiff.yaml still works; .oasdiff.yaml preferred when both exist; no-config not-an-error; --config explicit path; --config missing-file error; --config overrides default; OASDIFF_CONFIG env var; --config wins over env. All run in t.Chdir(t.TempDir()) for isolation.
• docs/CONFIG-FILES.md — new "Default lookup" + "Explicit override" sections, documents both default filenames, the precedence, and the two override mechanisms with runnable examples.
• examples/oasdiff.yaml → examples/.oasdiff.yaml — renamed to recommend the dotfile; the comment mentions the override mechanisms.

Backward compatibility

Strict — no existing setup breaks:

• Users with oasdiff.yaml in cwd: still works, no change needed.
• Users with no config file: still works, still no error.
• Users with the new .oasdiff.yaml: works, takes precedence over a co-existing oasdiff.yaml.

Test plan

• go test ./... — all packages green
• go test ./internal/ -run TestViper -count=1 -v — 20 tests pass (12 existing + 8 new)
• Manually verify oasdiff diff --config /tmp/x.yaml ... reads x.yaml
• Manually verify OASDIFF_CONFIG=/tmp/x.yaml oasdiff diff ... reads x.yaml
• Manually verify oasdiff diff ... with .oasdiff.yaml in cwd reads it
• Manually verify oasdiff diff ... with oasdiff.yaml (and no .oasdiff.yaml) in cwd reads it
• Manually verify oasdiff diff ... with both files prefers .oasdiff.yaml