v1.13.0

Summary

This release removes 11 deprecated package-level convenience functions from all core packages in preparation for a cleaner, more consistent API surface. All functionality remains available through the recommended struct-based API and functional options pattern.

Note on Versioning: While this release contains breaking changes, we are releasing it as a minor version bump (v1.13.0) rather than a major version because:

• The module is still relatively new with minimal library adoption
• Deprecated functions have been clearly marked in previous releases
• The recommended struct-based API (using *WithOptions pattern) remains unchanged
• Migration is straightforward and well-documented

See MIGRATION_V1.12_TO_V1.13.md for detailed migration guidance.

Breaking Changes

Removed Deprecated Functions

All deprecated package-level convenience functions have been removed. Users should migrate to the functional options pattern (*WithOptions) or struct-based API.

Parser Package (parser/parser.go):

• Removed Parse()
• Removed ParseReader()
• Removed ParseBytes()

Validator Package (validator/validator.go):

• Removed Validate()
• Removed ValidateParsed()

Converter Package (converter/converter.go):

• Removed Convert()
• Removed ConvertParsed()

Joiner Package (joiner/joiner.go):

• Removed Join()
• Removed JoinParsed()

Differ Package (differ/differ.go):

• Removed Diff()
• Removed DiffParsed()

Migration Example

// Before (v1.12.x and earlier):
result, err := parser.Parse("openapi.yaml", true, true)

// After (v1.13.0+):
result, err := parser.ParseWithOptions(
    parser.WithFilePath("openapi.yaml"),
    parser.WithResolveRefs(true),
    parser.WithValidateStructure(true),
)

Improvements

Code Quality

• Test Organization: Split parser_test.go (2,495 lines) into 6 focused test files for better maintainability (#58)
  • parser_test.go (core parsing)
  • parser_options_test.go (functional options API)
  • parser_refs_test.go (reference resolution)
  • parser_validation_test.go (validation)
  • parser_url_test.go (URL operations)
  • parser_utils_test.go (utilities)

Developer Experience

• Local Code Review: New pre-push Git hook for local code review using Claude CLI (#58)
  • ./scripts/install-git-hooks.sh - One-time setup
  • ./scripts/local-code-review.sh - Manual review anytime
  • Non-blocking pre-push hook for automated review

CI/CD

• Stability: Reduced test parallelism from -parallel=2 to -parallel=1 for more stable CI runs (#58)
• Timeouts: Added explicit step-level timeout to Go workflow Test step (#57)
• Resource Management: Increased go test timeout from 5m to 10m for first-run module downloads (#54, #55)

Documentation

• Migration Guide: Added comprehensive migration guide from v1.12.x to v1.13.0 (#58)
• API Reference: Fixed builder API reference and updated package count to 7 (#56)
• Code Review: Documented local code review workflow in CLAUDE.md (#58)

Related PRs

• #58 - feat: remove deprecated functions for v1.13.0 release
• #57 - fix: add explicit step-level timeout to Go workflow Test step
• #56 - docs: fix builder API reference and update package count
• #55 - ci: increase go test timeout from 5m to 10m in test command
• #54 - ci: increase Go workflow timeout from 5m to 10m for first-run module downloads

Installation

Homebrew

```bash
brew tap erraggy/oastools
brew install oastools
```

Go Module

```bash
go get github.com/erraggy/oastools@v1.13.0
```

Binary Download

Download the appropriate binary for your platform from the assets below.

Full Changelog

Full Changelog: v1.12.0...v1.13.0

v1.12.1

Summary

This is a documentation-only patch release that fixes inaccurate API references and updates package information for pkg.go.dev.

What's Fixed

Documentation Corrections

README.md: Fixed builder API example that used the removed Build() method. The example now correctly shows BuildOAS3() which was introduced in v1.12.0.

doc.go: Updated root package documentation to list all six packages (was incorrectly showing five). Added the builder package to the package list.

Why This Release

While these are documentation-only changes, they impact:

• pkg.go.dev - The primary API documentation site for Go packages
• GitHub README - First thing developers see when discovering the project
• Developer experience - Incorrect examples cause compilation errors

Publishing v1.12.1 ensures pkg.go.dev displays accurate, working examples.

Changes Since v1.12.0

• docs: fix builder API reference and update package count (#56)
• ci: increase go test timeout from 5m to 10m in test command (#55)
• ci: increase Go workflow timeout from 5m to 10m for first-run module downloads (#54)

Installation

Homebrew

brew update
brew upgrade oastools

Go Module

go get github.com/erraggy/oastools@v1.12.1

Binary Download

Download the appropriate binary for your platform from the assets below.

---

Full Changelog: v1.12.0...v1.12.1

v1.12.0

Summary

This release introduces the builder package, a powerful new feature for programmatically constructing OpenAPI Specification documents in Go using a fluent API with automatic reflection-based schema generation.

What's New

Builder Package - Programmatic OAS Construction

The builder package enables developers to construct OpenAPI specifications programmatically without writing YAML or JSON. It automatically generates OpenAPI-compatible schemas from Go types using reflection, making API documentation a natural part of your Go codebase.

Key Features:

• Fluent API - Build specifications using method chaining
• Automatic Schema Generation - Pass Go types directly; schemas are generated via reflection
• Full OAS Support - Works with both OAS 2.0 (Swagger) and OAS 3.x (3.0.0 through 3.2.0)
• Type-Safe - Leverage Go's type system for compile-time safety
• Struct Tags - Customize schemas with json and oas tags (description, format, enum, constraints, etc.)
• Advanced Types - Handles generics, embedded structs, circular references, time.Time, and more
• Document Modification - Import and extend existing OAS documents with FromDocument() and FromOAS2Document()
• Webhooks Support - Full support for OAS 3.1+ webhooks
• Security Schemes - Built-in support for all OpenAPI security schemes (API keys, OAuth2, OpenID Connect, etc.)

Quick Example:

package main

import (
    "net/http"
    "github.com/erraggy/oastools/builder"
    "github.com/erraggy/oastools/parser"
)

type User struct {
    ID    int64  `json:"id" oas:"description=Unique identifier"`
    Name  string `json:"name" oas:"minLength=1,maxLength=100"`
    Email string `json:"email" oas:"format=email"`
}

func main() {
    spec := builder.New(parser.OASVersion320).
        SetTitle("User API").
        SetVersion("1.0.0").
        AddServer("https://api.example.com", "Production server")

    spec.AddOperation(http.MethodGet, "/users",
        builder.WithOperationID("listUsers"),
        builder.WithResponse(http.StatusOK, []User{}),
    )

    spec.AddOperation(http.MethodPost, "/users",
        builder.WithOperationID("createUser"),
        builder.WithRequestBody("application/json", User{}),
        builder.WithResponse(http.StatusCreated, User{}),
    )

    // Build and write to file
    spec.WriteFile("openapi.yaml")
}

The builder automatically:

• Generates schemas for User struct with proper types and constraints from oas tags
• Registers schemas in components.schemas (OAS 3.x) or definitions (OAS 2.0)
• Creates proper $ref references throughout the document
• Handles array types, nested objects, and complex structures

Type Mapping:

The builder maps Go types to OpenAPI schemas:

• string → string
• int, int32 → integer (format: int32)
• int64 → integer (format: int64)
• float32 → number (format: float)
• float64 → number (format: double)
• bool → boolean
• []T → array (items from T)
• map[string]T → object (additionalProperties from T)
• struct → object (properties from fields)
• *T → schema of T (nullable)
• time.Time → string (format: date-time)
• Generics like Response[User] are fully supported with sanitized names

Documentation:

• See builder/doc.go for comprehensive package documentation
• Examples in builder/example_test.go demonstrate common patterns
• 94.8% test coverage with extensive unit tests

This package is ideal for:

• Generating API documentation from existing Go code
• Creating OpenAPI specs as part of your build process
• Keeping API documentation in sync with implementation
• Testing API contract compliance programmatically

Additional Improvements

• Enhanced Go module caching in CI workflows for faster build times
• Updated GitHub Copilot integration for consistent AI assistance

Related PRs

• #52 - Implement builder package for programmatic OpenAPI specification construction
• #53 - Pre-release cleanup and workflow optimization

Installation

Homebrew

brew tap erraggy/oastools
brew install oastools

Go Module

go get github.com/erraggy/oastools@v1.12.0

Binary Download

Download the appropriate binary for your platform from the assets below.

---

Full Changelog: v1.11.2...v1.12.0

v1.11.2

Summary

This maintenance release focuses on internal code quality improvements and CI performance optimizations. No user-facing features or API changes are included.

Improvements

• Code Quality: Refactored JSON marshaling code to reduce duplication using shared helper package
• CI Performance: Split fast tests from race detection for faster CI feedback (2x improvement)
• Project Maintenance: Cleaned up completed planning documents

Related PRs

• #47 - chore(planning): remove completed planning documents and update status
• #46 - refactor: implement review feedback improvements (Phases 1-3)
• #45 - perf(ci): split fast tests from race detection for better CI performance

Installation

Homebrew

brew tap erraggy/oastools
brew install oastools

Go Module

go get github.com/erraggy/oastools@v1.11.2

Binary Download

Download the appropriate binary for your platform from the assets below.

v1.11.0

Summary

This release enhances CLI usability by adding document statistics and tool version display to all commands, along with comprehensive documentation updates for the functional options API pattern.

What's New

🎯 Enhanced CLI Output (#44)

All CLI commands now display rich metadata including:

• Tool version - Verify which version of oastools is running
• Document statistics - Quick visibility into API complexity:
  • Path count
  • Operation count (including webhooks for OAS 3.1+)
  • Schema/component count

Example output:

OpenAPI Specification Validator
================================

oastools version: v1.11.0
Specification: api.yaml
OAS Version: 3.0.3
Source Size: 15.2 KiB
Paths: 12
Operations: 28
Schemas: 15
Load Time: 234µs
Total Time: 1.2ms

✓ Validation passed

Benefits:

• Understand API complexity at a glance
• Verify tool version in output logs
• Track API growth over time
• Better debugging and support (version info in error reports)

Affected commands: parse, validate, convert, join, diff

📚 Documentation Updates (#43)

Updated all package documentation to feature the *WithOptions API pattern as the primary approach:

• Functional options pattern now showcased first in godocs
• Struct-based API documented as alternative for advanced use cases
• Clearer examples of common workflows
• Better alignment with Go best practices

Technical Details

New Features

• parser.DocumentStats - Struct containing path, operation, and schema counts
• parser.GetDocumentStats() - Calculate statistics from parsed documents
• Automatic statistics calculation during parsing (zero overhead)
• Webhook operations counted for OAS 3.1+ documents

Performance

• ✅ Zero performance regression
• ✅ Statistics calculated in single pass during parsing
• ✅ Negligible memory overhead

Testing

• 100% test coverage for new statistics functionality
• Comprehensive edge case handling (nil documents, webhooks, all HTTP methods)
• All existing tests continue to pass

Related PRs

• #44 - feat(cli): add document statistics and tool version to CLI output
• #43 - docs: update all documentation to use *WithOptions APIs as primary

Installation

Homebrew

brew update
brew upgrade oastools
# or
brew install erraggy/oastools/oastools

Go Module

go get github.com/erraggy/oastools@v1.11.0

Binary Download

Download the appropriate binary for your platform from the assets below.

Full Changelog

v1.10.1...v1.11.0

v1.10.1

Summary

This patch release includes internal dependency cleanup, critical bug fixes for circular reference handling discovered through fuzz testing, and CI improvements to upgrade tooling.

Bug Fixes

• Parser: Fix infinite loops when resolving circular references (#41)
  • Fixed circular self-references in schemas (e.g., Node.next -> #/components/schemas/Node)
  • Fixed root document references ($ref: "#") causing infinite recursion
  • Added graceful fallback when YAML marshaling fails due to circular structures
  • All bugs discovered and validated through automated fuzz testing

New Features

• Parser: Add comprehensive fuzz testing infrastructure (#41)
  • New FuzzParseBytes fuzz test with 19-seed corpus from existing testdata
  • Configured Makefile target test-fuzz-parse with customizable duration (FUZZ_TIME)
  • Automatically preserves failing inputs as regression tests in testdata/fuzz/
  • Successfully discovered 2 critical infinite loop bugs during initial fuzzing session
  • Excluded from regular CI runs to maintain fast build times

Improvements

• Parser: Remove external go-version dependency (#42)

  • Implemented internal semver parser (~100 lines) replacing external dependency
  • Reduced project dependencies from 3 to 2
  • Added comprehensive test coverage (219 lines) including overflow protection
  • Maintains all existing functionality with no breaking changes

• CI: Upgrade golangci-lint from v2.1 to v2.6.2

  • Latest version as of November 2025
  • Fixes SA5011 false positives in test files (36 issues eliminated)
  • Properly recognizes t.Fatal() as a terminating statement

Fuzz Testing Impact

The addition of fuzz testing in this release immediately proved its value by discovering two critical bugs that would have caused parser hangs in production:

1. Circular Self-Reference Bug (corpus: 1183bda38794b4b0)

   • Schemas that reference themselves (e.g., linked list Node types) caused infinite expansion
   • Fixed by tracking refs in the current call stack with a resolving map

2. Root Document Reference Bug (corpus: 86518b4cae690792)

   • References to the document root ($ref: "#") caused infinite recursive expansion
   • Fixed by explicitly skipping resolution of # and #/ references

Both bugs are now preserved as regression tests in the fuzz corpus, ensuring they cannot reoccur.

Related PRs

• #42 - refactor(parser): remove go-version dependency, implement internal semver parser
• #41 - feat(parser): add fuzz testing and fix circular reference infinite loops

Installation

Homebrew

brew tap erraggy/oastools
brew upgrade oastools

Go Module

go get github.com/erraggy/oastools@v1.10.1

Binary Download

Download the appropriate binary for your platform from the assets below.

v1.10.0

Summary

This release significantly expands the differ package with comprehensive schema diffing capabilities, including support for recursive schemas, schema composition (allOf/anyOf/oneOf), and conditional schemas (if/then/else). The release also includes improved release management documentation and benchmark tooling.

What's New

Schema Diffing Enhancements

• Recursive Schema Diffing (Phase 1): Deep comparison of nested schema structures with circular reference detection
• Schema Composition Diffing (Phase 2): Support for allOf, anyOf, oneOf, and not combinators with proper semantic analysis
• Conditional Schema Diffing: if/then/else schema comparison with breaking change detection
• Specification Extensions: Support for diffing custom x-* extension properties

Developer Experience

• Unified Differ Implementation: Consolidated simple.go and breaking.go into a single, maintainable implementation
• Benchmark Tooling: New scripts for tracking performance over time and generating comparison reports
• Improved Test Coverage: Increased from 50.3% to 64.3%

Documentation

• Release Process: Updated documentation for GitHub's immutable releases feature with tag-first workflow
• Benchmark Update Process: Documented workflow for maintaining benchmark baselines

Improvements

• Consolidated differ implementation reduces code duplication and improves maintainability
• Enhanced benchmark tooling enables performance regression detection
• Security improvements addressing GitHub code scanning alerts (CWE-190, CWE-275)

Related PRs

• #40 - docs: update release process for immutable releases with tag-first workflow
• #38 - refactor(differ): consolidate simple.go and breaking.go into unified implementation
• #37 - chore: pre-release improvements and benchmark tooling for v1.10.0
• #36 - feat(differ): implement schema composition and conditional diffing (Phase 2)
• #34 - feat(differ): implement Phase 1 recursive schema diffing
• #33 - fix: address GitHub code scanning security alerts
• #32 - test: improve test coverage from 50.3% to 64.3%
• #28 - feat(differ): add support for diffing specification extensions (x-*)

Installation

Homebrew

```bash
brew tap erraggy/oastools
brew install oastools
```

Go Module

```bash
go get github.com/erraggy/oastools@v1.10.0
```

Binary Download

Download the appropriate binary for your platform from the assets below.

Breaking Changes

None - this release maintains backward compatibility with all existing APIs.

v1.9.12

Summary

Fixes macOS Gatekeeper "could not verify malware" errors when installing via Homebrew by reverting from Cask to Formula distribution.

What's Changed

Bug Fixes

• Homebrew Distribution: Reverted from homebrew_casks to brews configuration in GoReleaser
  • Casks require Apple Developer code signing and notarization ($99/year)
  • Formulas work without code signing, which is standard for CLI tools
  • Users can now install without encountering macOS security warnings

Technical Details

The v1.9.8 release migrated to using Homebrew Casks based on GoReleaser's deprecation of the old brews section. However, Casks are designed for GUI applications and require binaries to be signed and notarized by Apple. This caused installation failures for users.

While brews is deprecated in favor of homebrew_casks, it remains fully functional in GoReleaser v2.x and is the correct choice for unsigned CLI tools. The deprecation targets GUI apps moving to proper Cask distribution, not CLI tools.

Installation

Homebrew

brew tap erraggy/oastools
brew install oastools

After this release, the Formula will work without code signing issues.

Binary Download

Download the appropriate binary for your platform from the assets below.

Related Commits

• 79bdd7b - fix: revert to brews for Homebrew distribution to avoid code signing issues
• 6abc2e9 - docs: streamline CLAUDE.md by removing duplication and redundancy

v1.9.10 - Security Fixes for Integer Overflow Vulnerabilities

Summary

This release addresses critical security vulnerabilities identified by GitHub Code Scanning (CodeQL). Three security alerts have been resolved: two HIGH severity integer overflow issues and one MEDIUM severity workflow permissions issue.

Security Fixes

Integer Overflow Protection (CWE-190)

• Fixed: Size computation overflow in joiner/oas2.go when merging string slices
• Impact: Prevents potential integer overflow when computing slice capacity from len(a) + len(b)
• Solution: Platform-independent overflow guard using uint64 arithmetic and math.MaxInt
• Alerts: GitHub Code Scanning #2, #3 (HIGH severity)

Workflow Permissions Hardening (CWE-275)

• Fixed: Added explicit permissions: contents: read to GitHub Actions workflow
• Impact: Follows principle of least privilege, preventing accidental write access
• Alert: GitHub Code Scanning #5 (MEDIUM severity)

Technical Details

The overflow fix uses a three-stage approach:

1. uint64 arithmetic: Safely compute sum = uint64(len(a)) + uint64(len(b))
2. Platform-aware bounds check: Verify sum <= uint64(math.MaxInt)
3. Graceful degradation: Falls back to capacity 0 if overflow would occur

This approach works correctly on all platforms:

• 32-bit systems (386): Protects against overflow at ~2.1 billion elements
• 64-bit systems (amd64, arm64): Protects against overflow at ~9.2 quintillion elements

Documentation

New Documentation

• Security Audit: Comprehensive scan of all len() arithmetic patterns (planning/security-audit-len-arithmetic.md)
  • Identified 28 low-risk instances (map allocations with small constants)
  • Confirmed no additional critical vulnerabilities
  • Provides methodology and future monitoring recommendations

Updated Documentation

• CLAUDE.md: New security section with overflow fix patterns, examples, and workflow retrieval instructions
• Code references: Links documentation examples to actual implementation

Testing

• ✅ All 933 tests pass with race detection
• ✅ Coverage maintained at 64.3%
• ✅ New test: TestMergeUniqueStrings_OverflowSafety validates overflow protection behavior
• ✅ govulncheck reports no vulnerabilities

No Breaking Changes

• All public APIs remain unchanged
• No functional impact on existing code
• Overflow protection is transparent (graceful degradation)

Related PRs

• #33 - Fix GitHub code scanning security alerts

Installation

Homebrew

brew tap erraggy/oastools
brew install oastools
# Or upgrade existing installation
brew upgrade oastools

Go Install

go install github.com/erraggy/oastools/cmd/oastools@v1.9.10

Binary Download

Download the appropriate binary for your platform from the assets below.

Verification

To verify the security fixes:

# Check for Go vulnerabilities
go run golang.org/x/vuln/cmd/govulncheck@latest ./...

# Review the security audit
cat planning/security-audit-len-arithmetic.md

---

🛡️ This release demonstrates proactive security maintenance with comprehensive scanning and documentation. All GitHub Code Scanning alerts have been resolved.

v1.9.8 - Comprehensive Differ Enhancements

Summary

This release significantly enhances the differ package with comprehensive comparison capabilities for responses, schemas, and specification extensions. The differ now provides detailed field-by-field comparison with intelligent breaking change detection.

What's New

Extension (x-*) Field Diffing

• Full extension support: Detects and reports changes to specification extensions (x-* fields) across 15 different OAS object types
• Coverage: Document, Info, Server, PathItem, Operation, Parameter, RequestBody, Response, Header, Link, MediaType, Schema, SecurityScheme, Tag, and Components levels
• Smart classification: All extension changes are marked as informational (non-breaking) since extensions are non-normative

Comprehensive Response Comparison

• Headers: Compares all header properties including description, required, deprecated, type, style, schema, and extensions
• Content/MediaTypes: Compares media type objects and their schemas with proper severity assignment
• Links: Compares link objects (operationRef, operationId, description, extensions)
• Examples: Compares example map keys (structural comparison)

Comprehensive Schema Comparison

• Metadata: title, description
• Type information: type, format with breaking change detection
• Numeric constraints: multipleOf, maximum, exclusiveMaximum, minimum, exclusiveMinimum
• String constraints: maxLength, minLength, pattern
• Array constraints: maxItems, minItems, uniqueItems
• Object constraints: maxProperties, minProperties, required fields
• OAS-specific fields: nullable, readOnly, writeOnly, deprecated

Smart Severity Assignment

The differ now uses intelligent severity levels in breaking mode:

• ERROR: Stricter constraints that break compatibility (adding required fields, lowering max values, raising min values)
• WARNING: Changes that might affect consumers (type changes, constraint modifications)
• INFO: Relaxations and non-breaking changes (removing required fields, raising max values, lowering min values)

Changes

• feat(differ): add support for diffing specification extensions (#28)
• feat(differ): implement comprehensive response and schema comparison
• docs(differ): update coverage documentation for response and schema comparison
• fix(goreleaser): create releases as drafts to allow asset uploads (#31)
• fix(goreleaser): change release mode to replace for automated releases (#30)
• Added CategoryExtension for extension-specific changes
• Implemented comprehensive response comparison (7 functions for simple mode, 7 for breaking mode)
• Implemented comprehensive schema comparison (8 helper functions for field-by-field analysis)
• Enhanced documentation in differ/doc.go with detailed coverage information

Technical Details

Files Changed

• differ/differ.go - Added CategoryExtension constant
• differ/simple.go - +421 lines (12 new functions, 8 enhanced functions)
• differ/breaking.go - +857 lines (17 new functions, 8 enhanced functions)
• differ/doc.go - +112 lines (comprehensive documentation)
• differ/extensions_test.go - +889 lines (22 test cases)
• internal/httputil/httputil.go - +10 lines (minor improvements)
• .goreleaser.yaml - Fixed release configuration for draft mode

Code Quality

• All tests pass (22 extension-specific tests + comprehensive response/schema tests)
• Linter clean (0 issues)
• Cyclomatic complexity refactored to maintain standards
• Test coverage: 54.7% for differ package

Related Issues

• Resolves #27 - Add extensions (Extras) to diffing

Installation

Homebrew

```bash
brew tap erraggy/oastools
brew install oastools
```

Binary Download

Download the appropriate binary for your platform from the assets below.

Breaking Changes

None. This release is fully backward compatible.

Upgrade Notes

No special migration steps required. Simply upgrade to v1.9.8 to gain access to the enhanced differ capabilities.