chore: bump minimum Go from 1.24 to 1.25

.github/CONFIGURATION.md

@@ -39,7 +39,7 @@ Both instruction files follow [GitHub's best practices](https://docs.github.com/
 
 - ✅ Clear project purpose and overview
 - ✅ Specific build, test, and lint commands
-- ✅ Detailed tech stack information (Go 1.24, frameworks, dependencies)
+- ✅ Detailed tech stack information (Go 1.25, frameworks, dependencies)
 - ✅ Code style guidelines with real examples
 - ✅ Explicit acceptance criteria for task completion
 - ✅ Clear boundaries (files/directories that should not be modified)

.github/copilot-instructions.md

@@ -120,7 +120,7 @@ export PATH=$PATH:$(go env GOPATH)/bin
 
 # Verify installation
 golangci-lint version
-# Expected output: golangci-lint has version 2.1.0 built with go1.24.2...
+# Expected output: golangci-lint has version 2.1.0 built with go1.25...
 ```
 
 **Without golangci-lint v2 installed, `make check` and `make lint` will fail.**
@@ -313,7 +313,7 @@ For documentation-only changes, only items 3, 6, and 7 apply.
 **DO NOT:**
 
 - Add dependencies without checking for security vulnerabilities first
-- Modify benchmark test patterns (must use Go 1.24 `for b.Loop()` pattern)
+- Modify benchmark test patterns (must use Go 1.24+ `for b.Loop()` pattern)
 - Remove or weaken existing test coverage
 - Change public API signatures without documenting breaking changes
 - Commit secrets, credentials, or sensitive data
@@ -322,7 +322,7 @@ For documentation-only changes, only items 3, 6, and 7 apply.
 ## Go Module
 
 - Module path: `github.com/erraggy/oastools`
-- Minimum Go version: 1.24
+- Minimum Go version: 1.25
 
 ## Public API Structure
 

.github/workflows/benchmark.yml

@@ -59,7 +59,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v6
         with:
-          go-version: '1.24'
+          go-version: '1.25'
           cache: true
 
       - name: Run benchmarks for ${{ matrix.package }}

.github/workflows/go-race.yml

@@ -19,9 +19,6 @@ on:
 permissions:
   contents: read
 
-env:
-  GOEXPERIMENT: synctest  # Required for testing/synctest. Remove when Go 1.25+.
-
 jobs:
 
   race-test:
@@ -33,7 +30,7 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v6
       with:
-        go-version: '1.24'
+        go-version: '1.25'
         cache: true
 
     - name: Test parser package with Race Detector

.github/workflows/go.yml

@@ -12,9 +12,6 @@ on:
 permissions:
   contents: read
 
-env:
-  GOEXPERIMENT: synctest  # Required for testing/synctest. Remove when Go 1.25+.
-
 jobs:
 
   build:
@@ -28,7 +25,7 @@ jobs:
     - name: Set up Go
       uses: actions/setup-go@v6
       with:
-        go-version: '1.24'
+        go-version: '1.25'
         cache: true
 
     - name: Install dependencies

.github/workflows/golangci-lint.yml

@@ -10,9 +10,6 @@ permissions:
   # Optional: allow read access to pull requests. Use with `only-new-issues` option.
   # pull-requests: read
 
-env:
-  GOEXPERIMENT: synctest  # Required for testing/synctest. Remove when Go 1.25+.
-
 jobs:
   golangci:
     name: lint
@@ -21,7 +18,7 @@ jobs:
       - uses: actions/checkout@v6
       - uses: actions/setup-go@v6
         with:
-          go-version: 1.24
+          go-version: '1.25'
           cache: true
       - name: golangci-lint
         uses: golangci/golangci-lint-action@v8

.github/workflows/release.yml

@@ -21,7 +21,7 @@ jobs:
       - name: Set up Go
         uses: actions/setup-go@v6
         with:
-          go-version: '1.24'
+          go-version: '1.25'
 
       - name: Run GoReleaser
         uses: goreleaser/goreleaser-action@v6

AGENTS.md

@@ -9,7 +9,7 @@ This file provides quick, actionable guidance for AI coding agents working on th
 `oastools` is a Go-based CLI tool for working with OpenAPI Specification (OAS) files. It supports parsing, validating, fixing, joining, converting, and comparing OAS documents across versions 2.0, 3.0.x, 3.1.x, and 3.2.0.
 
 **Module:** `github.com/erraggy/oastools`  
-**Go Version:** 1.24+
+**Go Version:** 1.25+
 
 ## Dev Environment Setup
 

CLAUDE.md

@@ -47,7 +47,6 @@
 - **`make check` before pushing** — not just `go test`; catches lint, formatting, and trailing whitespace
 - **`docs/` is mixed source + generated**: Source files (`index.md`, `mcp-server.md`, `cli-reference.md`, etc.) are edited directly in `docs/`. Generated files (`docs/packages/`, `docs/examples/`) come from `{package}/deep_dive.md` and `examples/*/README.md` — see `.claude/docs/docs-website.md`
 - **MCP config via env vars**: The MCP server reads `OASTOOLS_*` env vars for configuration (cache TTLs, walk limits, join strategies, etc.). The Go MCP SDK doesn't support `initializationOptions`, so env vars are used instead. MCP clients set these via their `env` field in server config.
-- **`GOEXPERIMENT=synctest`**: Required for `testing/synctest` (deterministic fake-clock tests). The Makefile exports this globally. Remove when Go 1.25+ (where synctest is GA). Use `make test`, not bare `go test`.
 
 ## Orchestrator Mode
 
@@ -86,4 +85,4 @@
 ## Go Module
 
 - **Module**: `github.com/erraggy/oastools`
-- **Minimum Go**: 1.24
+- **Minimum Go**: 1.25

CONTRIBUTORS.md

@@ -17,7 +17,7 @@ Thank you for your interest in contributing to oastools! This document provides
 
 ### Prerequisites
 
-- **Go 1.24+** - Required for development
+- **Go 1.25+** - Required for development
 - **golangci-lint** - For linting (optional but recommended)
 - **gotestsum** - For better test output formatting (optional)
 

Makefile

@@ -5,17 +5,14 @@ MAIN_PATH=./cmd/oastools
 BENCH_DIR=benchmarks
 BENCH_TIME=5s
 
-# Pin to Go 1.24 toolchain even when a newer Go is installed system-wide.
-# GOROOT points tools (including golangci-lint) to the correct SDK.
-# GOEXPERIMENT=synctest required for testing/synctest (experimental in 1.24, GA in 1.25+).
-# Remove all four lines when min Go >= 1.25.
-GO1_24_SDK := $(wildcard $(HOME)/sdk/go1.24.13)
-QUALITY_TARGETS := test test-quick test-race test-full test-coverage test-corpus test-corpus-short integration-test integration-test-debug count-tests count-benchmarks lint vet
-ifneq ($(GO1_24_SDK),)
-$(QUALITY_TARGETS): export GOROOT = $(GO1_24_SDK)
-$(QUALITY_TARGETS): export PATH := $(GO1_24_SDK)/bin:$(PATH)
+# Pin GOROOT to the SDK matching go.mod when system Go is older.
+# Update the version here when bumping go.mod's go directive.
+GO_SDK := $(wildcard $(HOME)/sdk/go1.25.8)
+QUALITY_TARGETS := tidy fmt test test-quick test-race test-full test-coverage test-corpus test-corpus-short integration-test integration-test-debug count-tests count-benchmarks lint vet
+ifneq ($(GO_SDK),)
+$(QUALITY_TARGETS): export GOROOT = $(GO_SDK)
+$(QUALITY_TARGETS): export PATH := $(GO_SDK)/bin:$(PATH)
 endif
-$(QUALITY_TARGETS): export GOEXPERIMENT = synctest
 
 # Default target
 all: build

README.md

@@ -73,7 +73,7 @@ Pre-built binaries for macOS, Linux, and Windows on the [Releases](https://githu
 go get github.com/erraggy/oastools@latest
 ```
 
-Requires Go 1.24+.
+Requires Go 1.25+.
 
 ## Documentation
 

benchmarks.md

@@ -6,8 +6,8 @@ This document provides detailed performance analysis and benchmark results for t
 
 As of v1.18.0, oastools includes comprehensive performance benchmarking infrastructure covering all major operations across the parser, validator, fixer, converter, joiner, differ, generator, builder, and overlay packages. The library has undergone targeted optimizations to achieve significant performance improvements while maintaining correctness and code quality.
 
-**CI Platform (for cross-version comparisons)**: linux/amd64, AMD EPYC 7763, Go 1.24
-**Local Platform (historical reference)**: darwin/arm64, Apple M4, Go 1.24
+**CI Platform (for cross-version comparisons)**: linux/amd64, AMD EPYC 7763, Go 1.25
+**Local Platform (historical reference)**: darwin/arm64, Apple M4, Go 1.25
 
 > **Note:** CI-generated benchmarks (`benchmarks/benchmark-v*.txt`) provide consistent, reproducible results for cross-version comparisons. Local benchmarks (`benchmarks/local/`) are preserved for historical reference but have ±50% I/O variance.
 

docs/claude-code-plugin.md

@@ -17,7 +17,7 @@ brew install erraggy/oastools/oastools
 **Go install:**
 
 ```bash
-# Requires Go 1.24+
+# Requires Go 1.25+
 go install github.com/erraggy/oastools/cmd/oastools@latest
 ```
 

docs/index.md

@@ -118,7 +118,7 @@ Pre-built binaries for macOS, Linux, and Windows on the [Releases](https://githu
 go get github.com/erraggy/oastools@latest
 ```
 
-Requires Go 1.24+.
+Requires Go 1.25+.
 
 ---
 

docs/mcp-server.md

@@ -8,7 +8,7 @@ The MCP server is built into the `oastools` binary. Install it first:
 
 ```bash
 brew install erraggy/oastools/oastools                   # Homebrew (macOS/Linux)
-go install github.com/erraggy/oastools/cmd/oastools@latest  # Go install (requires Go 1.24+)
+go install github.com/erraggy/oastools/cmd/oastools@latest  # Go install (requires Go 1.25+)
 ```
 
 Or download a pre-built binary from the [Releases page](https://github.com/erraggy/oastools/releases/latest).

docs/whitepaper.md

@@ -112,7 +112,7 @@ oastools implements [JSONPath per RFC 9535](https://datatracker.ietf.org/doc/htm
 
 ### 2.3 Go Language Specification
 
-oastools targets [Go 1.24+](https://go.dev/doc/go1.24) and leverages language features accordingly. The toolkit uses generics for type-safe operations where appropriate, Go 1.24 benchmark patterns with `b.Loop()` for accurate performance measurement, and standard library patterns for HTTP handling that integrate with `net/http`. The [generator package](#11-generator-package) produces code compatible with Go 1.18+ when using generics for optional types.
+oastools targets [Go 1.25+](https://go.dev/doc/go1.25) and leverages language features accordingly. The toolkit uses generics for type-safe operations where appropriate, Go 1.24+ benchmark patterns with `b.Loop()` for accurate performance measurement, and standard library patterns for HTTP handling that integrate with `net/http`. The [generator package](#11-generator-package) produces code compatible with Go 1.18+ when using generics for optional types.
 
 ### 2.4 Related RFCs
 
@@ -2392,7 +2392,7 @@ The modular architecture allows teams to adopt individual packages as needed whi
 
 15. **The Go Programming Language Specification.** [https://go.dev/ref/spec](https://go.dev/ref/spec)
 
-16. **Go 1.24 Release Notes.** [https://go.dev/doc/go1.24](https://go.dev/doc/go1.24)
+16. **Go 1.25 Release Notes.** [https://go.dev/doc/go1.25](https://go.dev/doc/go1.25)
 
 ### oastools Documentation
 

examples/petstore/README.md

@@ -10,7 +10,7 @@ A comprehensive code generation example demonstrating the full capabilities of o
 
 ## Prerequisites
 
-- Go 1.24+
+- Go 1.25+
 - oastools CLI installed (`go install github.com/erraggy/oastools/cmd/oastools@latest`)
 
 ## Variants

examples/petstore/chi/go.mod

@@ -1,6 +1,6 @@
 module petstore-chi
 
-go 1.24.0
+go 1.25.8
 
 require github.com/erraggy/oastools v1.45.3
 

examples/petstore/stdlib/go.mod

@@ -1,6 +1,6 @@
 module petstore-stdlib
 
-go 1.24.0
+go 1.25.8
 
 require github.com/erraggy/oastools v1.45.3
 

examples/programmatic-api/builder/README.md

@@ -14,7 +14,7 @@ Demonstrates programmatic OpenAPI specification construction using the builder p
 
 ## Prerequisites
 
-- Go 1.24+
+- Go 1.25+
 
 ## Quick Start
 

examples/programmatic-api/builder/go.mod

@@ -1,12 +1,12 @@
 module builder
 
-go 1.24.0
+go 1.25.8
 
 require github.com/erraggy/oastools v1.45.3
 
 require (
 	go.yaml.in/yaml/v4 v4.0.0-rc.4 // indirect
-	golang.org/x/text v0.34.0 // indirect
+	golang.org/x/text v0.35.0 // indirect
 )
 
 replace github.com/erraggy/oastools => ../../../

examples/programmatic-api/builder/go.sum

@@ -11,5 +11,6 @@ golang.org/x/text v0.32.0 h1:ZD01bjUt1FQ9WJ0ClOL5vxgxOI/sVCNgX1YtKwcY0mU=
 golang.org/x/text v0.32.0/go.mod h1:o/rUWzghvpD5TXrTIBuJU77MTaN0ljMWE47kxGJQ7jY=
 golang.org/x/text v0.33.0/go.mod h1:LuMebE6+rBincTi9+xWTY8TztLzKHc/9C1uBCG27+q8=
 golang.org/x/text v0.34.0/go.mod h1:homfLqTYRFyVYemLBFl5GgL/DWEiH5wcsQ5gSh1yziA=
+golang.org/x/text v0.35.0/go.mod h1:khi/HExzZJ2pGnjenulevKNX1W67CUy0AsXcNubPGCA=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=

examples/quickstart/README.md

@@ -10,7 +10,7 @@ A minimal 5-minute introduction to oastools, demonstrating the parse and validat
 
 ## Prerequisites
 
-- Go 1.24+
+- Go 1.25+
 - oastools module dependency (auto-fetched)
 
 ## Quick Start

examples/quickstart/go.mod

@@ -1,6 +1,6 @@
 module quickstart
 
-go 1.24.0
+go 1.25.8
 
 require github.com/erraggy/oastools v1.45.3
 

examples/validation-pipeline/README.md

@@ -11,7 +11,7 @@ Demonstrates a complete validation pipeline with source map integration for IDE-
 
 ## Prerequisites
 
-- Go 1.24+
+- Go 1.25+
 - An OpenAPI specification file to validate
 
 ## Quick Start

examples/validation-pipeline/go.mod

@@ -1,6 +1,6 @@
 module validation-pipeline
 
-go 1.24.0
+go 1.25.8
 
 require github.com/erraggy/oastools v1.45.3
 

examples/walker/api-documentation/README.md

@@ -11,7 +11,7 @@ Demonstrates generating Markdown API documentation from OpenAPI specifications u
 
 ## Prerequisites
 
-- Go 1.24+
+- Go 1.25+
 
 ## Quick Start
 

examples/walker/api-documentation/go.mod

@@ -1,6 +1,6 @@
 module api-documentation
 
-go 1.24.0
+go 1.25.8
 
 require github.com/erraggy/oastools v1.45.3
 

examples/walker/api-statistics/README.md

@@ -12,7 +12,7 @@ Demonstrates collecting API statistics in a single pass using multiple walker ha
 
 ## Prerequisites
 
-- Go 1.24+
+- Go 1.25+
 
 ## Quick Start
 

examples/walker/api-statistics/go.mod

@@ -1,6 +1,6 @@
 module api-statistics
 
-go 1.24.0
+go 1.25.8
 
 require github.com/erraggy/oastools v1.45.3
 

examples/walker/public-api-filter/README.md

@@ -11,7 +11,7 @@ Demonstrates extracting public-facing API endpoints by filtering out internal, a
 
 ## Prerequisites
 
-- Go 1.24+
+- Go 1.25+
 
 ## Quick Start
 

examples/walker/public-api-filter/go.mod

@@ -1,6 +1,6 @@
 module public-api-filter
 
-go 1.24.0
+go 1.25.8
 
 require github.com/erraggy/oastools v1.45.3
 

examples/walker/reference-collector/README.md

@@ -12,7 +12,7 @@ Demonstrates analyzing schema references and detecting circular references using
 
 ## Prerequisites
 
-- Go 1.24+
+- Go 1.25+
 
 ## Quick Start
 

examples/walker/reference-collector/go.mod

@@ -1,6 +1,6 @@
 module reference-collector
 
-go 1.24.0
+go 1.25.8
 
 require github.com/erraggy/oastools v1.45.3
 

examples/walker/security-audit/README.md

@@ -11,7 +11,7 @@ Demonstrates auditing OpenAPI specifications for security issues using custom va
 
 ## Prerequisites
 
-- Go 1.24+
+- Go 1.25+
 
 ## Quick Start