feat: introducing transformers

[Azhovan]

What

Add an opt-in typed transformer stage to Rigging's load pipeline, plus docs and examples for the new API.

This PR is scoped to the transformer feature only (and its direct tests/docs/examples), specifically:

• Add Transformer[T], TransformerFunc[T], and Loader.WithTransformer(...) in loader.go
• Run transformers after bind/defaults/type conversion and before tag validation in Loader.loadInternal
• Add loader tests covering transformer registration and pre-validation canonicalization in loader_test.go
• Add GoDoc example ExampleLoader_WithTransformer in example_test.go
• Add runnable example examples/transformer/main.go and index it in examples/README.md
• Document the API and stage ordering in docs/api-reference.md

Why

Users often need to canonicalize typed config values (trim/lowercase/derive fields) before tag validation runs.

Without a dedicated stage, the only workaround is mutating inside WithValidator(...), which is:

• semantically unclear (validators are expected to validate, not mutate)
• too late for tag validation (oneof, min/max, etc.)

This feature provides a clear, explicit hook for typed value transforms while preserving:

• strict-mode key handling (still happens before bind)
• source/key normalization responsibilities (still belong in sources/source wrappers)
• presence-based required semantics (tracked during binding)

Type

• Fix
• Feature
• Docs
• Performance
• Breaking change

Testing

Executed and verified:

gofmt -w loader.go loader_test.go
gofmt -w example_test.go
gofmt -w examples/transformer/main.go
go test ./...

Result:

• go test ./... passed (including compile checks for examples/transformer)

Would run (not executed in this change set):

go vet ./...
make ci

Checklist

• Tests pass (go test ./...)
• Formatted (gofmt -s -w .)
• No vet warnings (go vet ./...)
• Coverage maintained (>70%)
• Added tests if needed
• Updated docs if needed

Notes:

• Formatted changed files with gofmt -w (not repo-wide gofmt -s -w .)
• Coverage was not measured in this change

---

For reviewers: Does this align with Rigging's philosophy of simplicity and zero dependencies?

[Copilot]

Pull request overview

This PR introduces an opt-in typed transformer stage to Rigging's configuration loading pipeline. The transformer feature allows users to canonicalize or derive typed configuration values after binding/defaults/type conversion but before tag-based validation runs. This addresses a real need where users previously had to mutate config inside validators, which was semantically unclear and ran too late for tag validation constraints.

Changes:

• Added Transformer[T] interface and TransformerFunc[T] adapter with execution logic in the load pipeline
• Added comprehensive test coverage for transformer registration and pre-validation execution
• Added documentation in API reference, README, runnable example, and GoDoc example

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
loader.go	Adds Transformer interface, TransformerFunc adapter, WithTransformer method, and transformer execution in loadInternal between binding and tag validation
loader_test.go	Adds tests for transformer initialization, registration, and pre-validation execution order
examples/transformer/main.go	New runnable example demonstrating environment variable canonicalization before oneof validation
example_test.go	Adds ExampleLoader_WithTransformer GoDoc example
examples/basic/main.go	Refactored to extract helper functions into separate files (no functional change)
examples/basic/config.go	Extracted config types and validator from main.go
examples/basic/output.go	Extracted output formatting functions from main.go
examples/README.md	Added transformer example to the index
docs/api-reference.md	Documents Transformer interface, TransformerFunc, and updated load pipeline description
README.md	Updated "Policy-Driven Validation" section to mention transformers and added transformer example

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.