feat: return a typed *config.Error with per-field causes

[JeremyLoy]

Stack 4/7. Base: #16.

To and Sub now return a *config.Error instead of a plain fmt.Errorf string. Error() produces exactly the same text as before, so existing output and string comparisons keep working.

API

type FieldError struct {
	Key string // "port", "sub__hosts[1]", "file[dev.config]"
	Err error  // cause; never contains the configured value
}
type Error struct{ Errors []*FieldError } // sorted by Key
func (*Error) Unwrap() []error

var ErrUnsupportedType, ErrInvalidValue error

Callers can now check what went wrong:

if cfgErr, ok := errors.AsType[*config.Error](err); ok { ... }
errors.Is(err, fs.ErrNotExist)   // a file is missing
errors.Is(err, strconv.ErrRange) // e.g. PORT=128 for an int8 field

Secrets are still kept out of errors

The library previously reported only a true/false result for each field so that configured values never ended up in logs. The new causes keep that guarantee:

• *strconv.NumError is reduced to its Err (ErrSyntax or ErrRange).
• Other parse failures become ErrInvalidValue.
• Unsupported field types become ErrUnsupportedType.

Test_typedErrors checks that a value like SECRET=hunter2 doesn't appear in any error.

Verification

gofmt, vet, staticcheck and go test -race pass on go1.26 and go1.27. Example_errorInspection is added.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NUxivLjodSESTkzRtdQ4CP

---

Generated by Claude Code