chore(docs): PR 1.6 add documentation and linting configuration for v3

[developerkunal]

📝 Checklist

• All new/changed/fixed functionality is covered by tests (or N/A)
• I have added documentation for all new/changed functionality (or N/A)

🔧 Changes

This PR adds comprehensive documentation and linting configuration for v3:

Documentation Added:

• doc.go package documentation for all packages:
  • Main package: Architecture overview, quick start, examples
  • core/doc.go: Core-Adapter pattern, context helpers
  • validator/doc.go: JWT validation with jwx v3, supported algorithms
  • jwks/doc.go: JWKS provider configuration and caching
  • internal/oidc/doc.go: OIDC discovery endpoints

Documentation Updated:

• README.md: Complete v3 API documentation
  • Added working JWT examples with curl commands
  • Updated Go version requirement to 1.24+
  • Included correct import paths
  • Added "Try it out" section with test tokens
• MIGRATION_GUIDE.md: Complete v2 to v3 migration guide
  • Side-by-side API comparisons
  • Step-by-step migration instructions
  • Updated to reflect v3 API accurately (GetClaimsT usage, no exported ContextKey)

Linting Configuration:

• .golangci.yml: golangci-lint v2.6.2 configuration
  • 16 linters enabled with appropriate settings
  • Test files excluded from linting
• .github/workflows/lint.yaml: Updated to use golangci-lint-action v9.1.0 with v2.6.2
• Makefile: Added golangci-lint v2.6.2 installation target

Code Cleanup:

• Removed validator/security.go and validator/security_test.go
  • CVE-2025-27144 mitigation no longer needed with jwx v3
• Removed CVE references from all documentation
• Fixed linting issues: Body.Close error handling, formatting

Types/Functions Changed:

• No API changes - documentation and configuration only
• Existing public API remains unchanged

📚 References

• Depends on PR refactor: PR 1.5 implement pure options pattern for middleware with core integration #360 (v3-phase1-pr5-middleware-options)
• Part of Phase 1 v3 development

🔬 Testing

Test Coverage:

• Main middleware: 98.2%
• Core: 100%
• Validator: 100%
• JWKS: 100%
• OIDC: 100%
• Overall: 99.4%

Linting:

• Production code: 0 issues
• Test files: Excluded

Manual Testing:

# Verify linting
make lint

# Verify tests
make test

# Verify examples compile
cd examples/http-example && go build
cd examples/http-jwks-example && go test

# Test JWT from README
curl -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnby1qd3QtbWlkZGxld2FyZS1leGFtcGxlIiwiYXVkIjoiYXVkaWVuY2UtZXhhbXBsZSIsInN1YiI6IjEyMzQ1Njc4OTAiLCJuYW1lIjoiSm9obiBEb2UiLCJpYXQiOjE1MTYyMzkwMjIsInVzZXJuYW1lIjoidXNlcjEyMyJ9.XFhrzWzntyINkgoRt2mb8dES84dJcuOoORdzKfwUX70" \
  http://localhost:3000

Verification:

• All godoc examples are valid Go code
• JWT tokens in documentation work with examples
• All examples compile and tests pass

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.86%. Comparing base (54615e2) to head (c3e8206).

Additional details and impacted files

@@                         Coverage Diff                          @@
##           v3-phase1-pr5-middleware-options     #361      +/-   ##
====================================================================
- Coverage                             98.88%   98.86%   -0.02%     
====================================================================
  Files                                    13       12       -1     
  Lines                                   718      707      -11     
====================================================================
- Hits                                    710      699      -11     
  Misses                                    4        4              
  Partials                                  4        4              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.