If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/spf13/viper shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• Last commit 4mo ago
• 11 active contributors
• Distributed ownership (top contributor 36% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 4mo ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live spf13/viper repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/spf13/viper.

What it runs against: a local clone of spf13/viper — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in spf13/viper | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 147 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of spf13/viper. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/spf13/viper.git
#   cd viper
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of spf13/viper and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "spf13/viper(\\.git)?\\b" \\
  && ok "origin remote is spf13/viper" \\
  || miss "origin remote is not spf13/viper (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "viper.go" \\
  && ok "viper.go" \\
  || miss "missing critical file: viper.go"
test -f "encoding.go" \\
  && ok "encoding.go" \\
  || miss "missing critical file: encoding.go"
test -f "file.go" \\
  && ok "file.go" \\
  || miss "missing critical file: file.go"
test -f "finder.go" \\
  && ok "finder.go" \\
  || miss "missing critical file: finder.go"
test -f "flags.go" \\
  && ok "flags.go" \\
  || miss "missing critical file: flags.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 147 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~117d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/spf13/viper"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Viper is a complete configuration management library for Go applications that merges settings from multiple sources (files, environment variables, command-line flags, remote systems like Etcd) into a single registry. It supports 12-Factor app patterns and provides live watching, dynamic discovery across multiple config locations, and unmarshaling into Go structs via mapstructure. Single-package library with modular encoding backends. Core logic in root-level files (viper.go implied, encoding.go, flags.go, file.go, finder.go) handles orchestration; internal/encoding/ contains pluggable codec implementations for JSON, YAML, TOML, and dotenv formats in subdirectories, each with their own codec.go and codec_test.go. No monorepo structure—pure library design.

Go application developers building production systems (Hugo, Docker Notary, DigitalOcean's doctl, Vitess) who need flexible, multi-source configuration without writing custom parsing logic. Also framework authors like Cobra who need to integrate config management into CLI tools.

Production-ready and actively maintained. The project has significant real-world adoption (Hugo, Docker, DigitalOcean), comprehensive CI/CD via GitHub Actions (.github/workflows/ci.yaml), extensive test coverage (encoding_test.go, finder_test.go, flags_test.go), and Go 1.23+ support. Currently on v1 with v2 in feedback stage—no abandonment signals.

Low risk for a core library. Dependencies are minimal and stable (fsnotify, mapstructure/v2, yaml.in, go-toml/v2, spf13/afero). The spf13 maintainer roster is known in the Go ecosystem but this is a single-author project; however, it has been stable for years. Breaking changes are tracked in UPGRADE.md, indicating careful versioning discipline.

Project is soliciting feedback for Viper v2 (see README form link). CI workflows are active (.github/workflows/checks.yaml, ci.yaml). Internal structure shows recent codec modernization with v2 suffix on mapstructure dependency (go-viper/mapstructure/v2 v2.4.0). Dependabot is configured (.github/dependabot.yaml) indicating automated dependency management is active.

git clone https://github.com/spf13/viper.git && cd viper && go mod download && go test ./... to run tests. For single-file exploration: go get github.com/spf13/viper@latest in any Go 1.23+ project.

Daily commands: This is a library—no server to run. Test it: make test (from Makefile) or go test ./.... The linter is configured in .golangci.yaml; run golangci-lint run to check code quality. Examples are inline as _test.go files (finder_example_test.go shows usage patterns).

• viper.go — Core Viper struct and main API surface; entry point for all configuration operations and must be understood before extending.
• encoding.go — Registry and dispatcher for all encoding/decoding handlers (JSON, YAML, TOML, dotenv); critical path for config file parsing.
• file.go — File watching and loading logic; responsible for detecting and reloading configuration changes via fsnotify.
• finder.go — Config file discovery and location logic; determines where configuration is read from across multiple search paths.
• flags.go — pflag integration and command-line flag binding; bridges CLI flags to configuration values.
• internal/encoding/yaml/codec.go — YAML encoding implementation; handles most complex use cases in practice due to YAML's richness.
• logger.go — Pluggable logging interface; understanding this enables debugging configuration loading issues.

• Viper (viper.go) (Go sync.RWMutex, context) — Central coordinator managing config lifecycle, merging sources, and exposing public API
  • Failure mode: If corrupted or locks indefinitely, all config access blocks; panic if struct corruption detected
• Finder (finder.go) (afero filesystem abstraction, filepath operations) — Searches filesystem for config files in specified paths; handles name/extension matching
  • Failure mode: Returns empty path if not found; caller must handle missing config gracefully
• File Loader (file.go) (fsnotify, afero, sync channels) — Reads raw bytes, watches for changes, triggers reloads, manages fsnotify subscription
  • Failure mode: Watch panics if cannot register inode; reload errors logged but don't stop app unless explicitly handled
• Encoding Registry (encoding.go + internal/encoding/*) (Go maps, codec interface pattern) — Dispatches bytes to correct codec; provides format detection and custom codec registration
  • Failure mode: Returns error if format unsupported or codec panics; caller must check error
• Flag Binding (flags.go) (spf13/) — Bridges pflag values into config tree; handles prefix matching and type coercion

Add support for a new configuration file format

1. Create a new codec package under internal/encoding/{format}/ with a Codec implementation (internal/encoding/{format}/codec.go)
2. Implement Marshal and Unmarshal methods conforming to the Codec interface (internal/encoding/{format}/codec.go)
3. Register the codec in encoding.go by adding an entry to the supported encodings map (encoding.go)
4. Add tests following the pattern in internal/encoding/{format}/codec_test.go (internal/encoding/{format}/codec_test.go)

Implement a custom configuration source (e.g., database or API)

1. Study the remote.go abstraction to understand the provider pattern (remote.go)
2. Create your provider implementing Get(key) and GetAll() methods (remote.go)
3. Call AddRemoteProvider() or AddSecureRemoteProvider() in your application setup (viper.go)
4. Add tests verifying integration with file.go's change detection via watchRemoteConfig() (file.go)

Add a new environment variable binding feature

1. Review existing flag binding patterns in flags.go for CLI integration (flags.go)
2. Add environment variable lookup logic to the config merging in util.go (util.go)
3. Expose new public method on Viper struct in viper.go (viper.go)
4. Add tests alongside existing viper_test.go patterns (viper_test.go)

Customize the configuration file discovery process

1. Review finder.go to understand the search path algorithm (finder.go)
2. Implement custom finder logic or override SetConfigSearchPath() calls (viper.go)
3. Add integration tests in finder_test.go showing your custom paths (finder_test.go)

• fsnotify — Cross-platform file system event monitoring for hot-reload; simpler than polling
• mapstructure/v2 — Robust struct unmarshaling with tag support and type coercion; handles nested config well
• spf13/pflag — POSIX-style flag parsing; integrates with Cobra CLI framework ecosystem
• go-toml/v2 + yaml.v3 + encoding/json — Pluggable multi-format support; users choose which formats to import and use
• afero — Abstract filesystem interface; enables testing without real files and multi-OS support

• Pluggable codec architecture instead of monolithic parser

  • Why: Reduces binary size for users only needing JSON; allows custom format support
  • Consequence: Slightly higher runtime overhead from registry lookup; more code to maintain

• Global singleton instance with optional multiple instances

  • Why: Simple API for common case; advanced users can create independent instances
  • Consequence: Global state can complicate testing and parallel scenarios; requires explicit v.New() for isolation

• File watching via fsnotify instead of stat polling

  • Why: Lower latency and CPU; works across Windows/Linux/macOS
  • Consequence: fsnotify requires kernel support; file move/delete edge cases are platform-specific

• Unmarshal via mapstructure instead of encoding/json struct tags

  • Why: Consistent behavior across all formats (YAML, TOML, JSON); better error messages
  • Consequence: Struct tag names differ from encoding/json; additional dependency needed

• Remote configuration from etcd/Consul/Kubernetes is provided via remote.go but optional and community-maintained
• Does not perform validation of configuration values (validation is application's responsibility)
• Does not include schema definition or enforced schema validation
• Does not provide built-in secrets management (users should integrate with HashiCorp Vault or similar)
• Does not handle application startup orchestration or dependency injection
• Not designed for high-frequency configuration updates or real-time distributed config sync

1. Environment variable binding via BindEnv() requires explicit key registration—not automatic for all config keys. 2) Config file discovery uses a search path order (AddConfigPath); if same key exists in multiple files, the first found wins, which can be unintuitive. 3) Type coercion via spf13/cast is automatic (GetString, GetInt, etc.) but may silently truncate or zero on type mismatch rather than error. 4) viper.Unmarshal() uses mapstructure tags, not json tags—a common gotcha for developers reusing struct definitions. 5) No built-in config validation; use external tools or custom code post-unmarshal.

• Configuration Precedence / Hierarchy — Viper merges configs from defaults → files → env vars → flags in a specific order; understanding this precedence prevents 'why is my env var not working?' bugs
• Codec / Pluggable Serialization — Viper's internal/encoding/ design allows swapping YAML, TOML, JSON, dotenv without core changes; knowing the codec interface lets you add custom formats
• File Watching / Watch Pattern — Viper uses fsnotify to watch config files for changes and reload—critical for apps needing live config updates without restart
• Struct Tag Unmarshaling (mapstructure) — Viper.Unmarshal() uses mapstructure tags (not json tags) to decode config into Go structs; using wrong tags is a common mistake
• Environment Variable Binding — BindEnv() and BindEnvWithPrefix() create explicit mappings from config keys to env var names; implicit env support is off by default unlike some competitors
• Registry Pattern — Viper acts as a singleton registry for all app config—Set/Get operations use a global viper instance; understanding this helps avoid state-sharing bugs in tests
• Type Casting / Type Coercion — Viper relies on spf13/cast to auto-convert config values (GetString, GetInt, GetBool) which can mask parsing errors; knowing cast behavior prevents silent truncation bugs

• spf13/cobra — Command-line framework that pairs with Viper for CLI apps; spf13 maintains both and they integrate natively for flag + config merging
• kelseyhightower/envconfig — Lightweight alternative for struct-based config from environment variables only; choose this if you only need env binding without multi-source merging
• caarlos0/env — Another minimal env→struct mapper; similar scope to envconfig but with a cleaner API; useful for projects that don't need Viper's complexity
• spf13/afero — Dependency of Viper; filesystem abstraction layer that Viper uses internally for config file I/O—understanding afero helps debug file discovery issues
• go-viper/mapstructure — Direct dependency (v2.4.0 in go.mod) that Viper uses for unmarshaling configs into Go structs; maintained fork after upstream archival

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive tests for internal/encoding/dotenv codec

The dotenv codec in internal/encoding/dotenv/ has codec.go and codec_test.go, but given that viper supports multiple configuration formats (YAML, TOML, JSON), the dotenv implementation likely lacks parity in test coverage. The map_utils.go helper file suggests complex parsing logic that needs edge case testing (multiline values, special characters, quoted strings, comments, empty lines).

• [ ] Review internal/encoding/dotenv/codec.go and internal/encoding/dotenv/map_utils.go for untested code paths
• [ ] Add tests in internal/encoding/dotenv/codec_test.go covering: multiline values, escaped characters, quoted strings with special chars, malformed syntax, empty files
• [ ] Add tests for internal/encoding/dotenv/map_utils.go if it contains exported utility functions
• [ ] Run go test -cover ./internal/encoding/dotenv to verify coverage reaches >90%

Add unit tests for remote configuration (remote/remote.go)

The remote/ subdirectory contains remote.go but there are no visible *_test.go files in the file structure. Remote configuration is a critical feature but lacks dedicated test coverage. This is especially important given it's in a separate go.mod module (remote/go.mod), suggesting it may be optional/experimental and thus at higher risk of being undertested.

• [ ] Create remote/remote_test.go with tests for core remote config operations
• [ ] Add tests covering: remote source connectivity, config retrieval, error handling for unavailable remotes, config parsing from remote sources
• [ ] Test integration with main viper package by creating tests that load remote configs via the main viper API
• [ ] Add tests for the experimental features referenced in experimental.go if they involve remote functionality

Add integration tests for bind_struct feature with defaults (internal/features/bind_struct_default.go)

The file structure shows internal/features/bind_struct.go and a separate internal/features/bind_struct_default.go, suggesting a recent refactor or feature split. The UPGRADE.md file indicates this is a v2-era project with breaking changes. There are likely missing integration tests validating the interaction between struct binding and default values, particularly edge cases around struct tags, nested structs, and override precedence.

• [ ] Review internal/features/bind_struct.go and internal/features/bind_struct_default.go to understand the default value binding logic
• [ ] Create internal/features/bind_struct_test.go or internal/features/bind_struct_default_test.go covering: nested struct defaults, tag-based defaults, override precedence, type coercion with defaults, missing optional fields
• [ ] Add cross-file integration tests validating that struct binding works correctly with viper's override system (viper.go, overrides_test.go)
• [ ] Ensure tests validate the v2 behavior mentioned in UPGRADE.md

• Add missing encoding_test.go coverage for error cases in dotenv codec (internal/encoding/dotenv/codec_test.go is skeletal—test parse errors, malformed key=value, unicode handling)
• Implement FindConfigFileInSearchPath() test for edge cases: symlinks, permissions denied, file disappears during search (finder_test.go exists but likely gaps remain)
• Add documentation with code examples for the less-obvious BindEnv() + AutomaticEnv() interaction in a new file docs/environment_variables.md—current README is terse

The Viper configuration library has a generally secure posture as a configuration management tool. Main concerns include: (1) A non-standard YAML fork that requires verification of its security maintenance, (2) Test dependencies incorrectly placed in production dependencies, (3) The inherent risk of configuration file handling which could expose sensitive data if misused. The codebase lacks visible injection vulnerabilities, hardcoded secrets in file names, or obvious Docker/infrastructure misconfigurations. Dependencies are well-maintained and relatively up-to-date. Recommendations focus on YAML library standardization, dependency cleanup, and reinforcing secure configuration handling practices in documentation.

• Medium · YAML Dependency with Known Vulnerabilities — go.mod - YAML dependencies. The project uses 'go.yaml.in/yaml/v3 v3.0.4' which is a fork of the standard YAML library. This fork has had security issues in the past. Additionally, the project also includes 'gopkg.in/yaml.v3 v3.0.1' as an indirect dependency, creating potential conflicts and version inconsistencies. Fix: Consider using the official 'gopkg.in/yaml.v3' package consistently. Verify that 'go.yaml.in/yaml' is from a trusted source and regularly check for security advisories. Consider pinning to a specific secure version and monitoring CVE databases.
• Low · Test Dependencies in Production — go.mod - testify dependency. The project includes 'github.com/stretchr/testify v1.11.1' in the main requires section. Testing libraries should typically be in development/test-only dependencies to avoid bloating production binaries and reducing the attack surface. Fix: Move testify to a separate go.mod file for tests or use build tags to exclude test code from production builds. Verify that test dependencies are not imported in non-test code.
• Low · Outdated Go Version — go.mod - go version declaration. The project targets Go 1.23.0. While this is relatively recent, it's recommended to stay on the latest stable version to receive security patches for the Go runtime and standard library. Fix: Regularly update the Go version to the latest stable release. Set up automated dependency checking and update CI/CD pipelines to test against new Go versions.
• Low · Potential Configuration File Exposure — file.go, encoding.go, viper.go. The codebase handles configuration files (.yaml, .toml, .json, .env formats). There is a risk of sensitive data (API keys, passwords, database credentials) being loaded from configuration files without proper validation or sanitization. The '.editorconfig' and '.yamlignore' files suggest configuration management, but hardcoded defaults or examples could leak secrets. Fix: Implement strict configuration validation, use environment variables for sensitive data instead of files, implement secure defaults, and add linting rules to detect hardcoded secrets. Use tools like gitleaks or similar to scan for accidental secret commits.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.