v1.9.4

Summary

Fixes an issue where the version was not being properly applied to the User-Agent header for HTTP requests made by the parser.

Changes

• fix(parser): Move version variable to root package for proper ldflags injection
• fix(parser): Ensure version is always applied to User-Agent by default
• refactor: Consolidate build details in root build_details.go file

Technical Details

The version information is now stored in a root-level build_details.go file, which allows the GoReleaser ldflags to properly inject the version during builds. This ensures that HTTP requests made by the parser include the correct version in the User-Agent header (e.g., oastools/v1.9.4).

Related PRs

• #26 - Fix parser to apply version to user-agent

Installation

Homebrew

brew tap erraggy/oastools
brew install oastools

Binary Download

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

v1.9.3

Summary

This patch release improves test coverage for the metrics feature introduced in v1.9.0 and switches to proper binary unit notation for file size formatting.

What's New

Test Coverage Improvements

• Add comprehensive tests for FormatBytes() function covering all byte size ranges (B, KiB, MiB, GiB, TiB, PiB, EiB)
• Add tests for LoadTime and SourceSize metrics in ParseResult
• Add tests verifying metric propagation from ParseResult to ValidationResult and ConversionResult
• All new exported functionality from v1.9.0 now has 100% test coverage

Code Quality Improvements

• Binary Unit Notation: File sizes now display using proper binary units (KiB, MiB, GiB) instead of decimal units (KB, MB, GB)
  • Aligns with IEC 60027-2 standard for binary prefixes
  • More accurate since calculations use base-1024
  • Example: 15.2 KiB instead of 15.2 KB
• Edge Case Handling: FormatBytes() now handles negative values gracefully and includes overflow protection

Documentation

• Add GitHub PR comment retrieval process to CLAUDE.md for easier workflow automation

Technical Details

File Size Display Changes:

Before: 15.2 KB, 5.0 MB, 1.0 GB
After:  15.2 KiB, 5.0 MiB, 1.0 GiB

This change affects the output of:

• oastools parse - Source Size display
• oastools validate - Source Size display
• oastools convert - Source Size display

Test Coverage:

• Added 244 lines of comprehensive test coverage
• All critical gaps from PR #24 addressed
• Linter: 0 issues
• All tests: PASS

Related PRs

• #25 - Fix: add missing test coverage and edge cases for metrics

Installation

Homebrew

brew tap erraggy/oastools
brew install oastools

Binary Download

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

Go Install

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

Full Changelog

Commits since v1.9.2:

• be59982 docs: add GitHub PR comment retrieval process to CLAUDE.md
• 128a2a4 fix: add missing test coverage and edge cases for metrics (#25)

v1.9.2

Summary

This release adds timing and size metrics to provide visibility into the performance characteristics of OpenAPI document loading and processing.

What's New

Timing Metrics

• Track time spent loading source documents (files, URLs, readers)
• Display total operation time for all CLI commands
• Separate load time from processing time for better analysis

Size Metrics

• Track source document size in bytes
• Human-readable size formatting (e.g., "15.2 KB", "2.3 MB")

CLI Enhancements

All commands now display relevant timing and size information:

parse command:

Source Size: 15.2 KB
Load Time: 2.5ms

validate command:

Source Size: 15.2 KB
Load Time: 2.5ms
Total Time: 45.3ms

convert command:

Source Size: 15.2 KB
Load Time: 2.5ms
Total Time: 127.8ms

join command:

Total Time: 89.2ms

diff command:

Total Time: 156.4ms

Changes

Library API

parser package:

• Added LoadTime time.Duration field to ParseResult
• Added SourceSize int64 field to ParseResult
• Added FormatBytes(int64) string function for human-readable size formatting

validator package:

• Added LoadTime and SourceSize fields to ValidationResult

converter package:

• Added LoadTime and SourceSize fields to ConversionResult

Technical Details

• Load time captures file I/O, URL fetching, or reader operations
• Total time includes parsing, validation/conversion/joining, and output
• Size is measured in bytes of raw source data
• Timing uses time.Duration for precision
• Format helper uses 1024-based units (KiB, MiB, etc.)

Installation

Homebrew

brew tap erraggy/oastools
brew upgrade oastools

Binary Download

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

Related PRs

• #24 - feat: add timing and size metrics to parse results

Notes

• All changes are backward compatible
• No breaking changes to public API
• New fields are additive only

v1.9.1

Summary

This patch release adds comprehensive benchmark coverage for the differ package and establishes benchmark testing standards for the project. The differ package now has 10 benchmarks covering all major operations, completing benchmark coverage for all five core packages.

What's New

Differ Package Benchmarks

• 10 comprehensive benchmarks covering all differ operations
  • Convenience functions (Diff, DiffParsed)
  • Struct-based API (Differ.Diff, Differ.DiffParsed)
  • Different modes (Simple, Breaking)
  • Configuration options (IncludeInfo)
  • Edge cases (IdenticalSpecs)
  • Parse-once pattern efficiency

Performance Highlights

• DiffParsed is 58x faster than Diff (7.8μs vs 457μs)
• Identical specs comparison: very fast at 2.8μs (fast path working)
• Breaking mode vs Simple mode: negligible difference (~0.15μs)
• Breaking change detection is essentially free from a performance perspective

Documentation Improvements

• New "Benchmark Test Requirements" section in CLAUDE.md
  • Documents required Go 1.24+ for b.Loop() pattern
  • Provides correct and incorrect examples
  • Explains consistency requirements across packages
• Updated benchmarks.md with differ performance metrics
• Updated README.md with differ benchmark statistics
• Enhanced Makefile with bench-differ target

Changes

New Files

• differ/differ_bench_test.go - 10 comprehensive benchmarks
• differ/bench-results.txt - Benchmark output results

Modified Files

• benchmarks.md - Added Differ Performance section, updated to 70+ benchmarks, v1.9.1
• README.md - Added differ benchmark metrics (58x speedup, 70+ total benchmarks)
• Makefile - Added bench-differ target, included differ in all benchmark targets
• CLAUDE.md - Added comprehensive benchmark testing standards and requirements

Technical Details

This release completes the benchmark coverage for all five core packages:

• ✅ parser (32 benchmarks)
• ✅ validator (12 benchmarks)
• ✅ converter (10 benchmarks)
• ✅ joiner (8 benchmarks)
• ✅ differ (10 benchmarks)

Total: 70+ benchmarks demonstrating the parse-once pattern's performance benefits across all operations.

The benchmark suite validates that the differ package follows the same high-performance patterns as other packages, with parsed operations showing dramatic speedups by avoiding re-parsing overhead.

Benchmark Testing Standards

All benchmarks now follow the modern Go 1.24+ for b.Loop() pattern for consistency and best practices. CLAUDE.md now documents this as a requirement for all future benchmark tests.

Installation

Homebrew

brew tap erraggy/oastools
brew upgrade oastools

Binary Download

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

Go Install

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

Related PRs

• #23 - Add comprehensive benchmark suite for differ package

🤖 Generated with Claude Code

v1.9.0

Summary

This release adds comprehensive OpenAPI specification comparison and breaking change detection capabilities through the new differ package and diff CLI command.

What's New

🆕 Diff Command and Differ Package

Compare OpenAPI specifications to identify differences and detect breaking changes that could affect API consumers.

Features:

• Two operational modes:
  • Simple mode: Reports all semantic differences
  • Breaking mode: Categorizes changes by severity and identifies breaking changes
• Comprehensive change detection across all OAS elements
• Smart severity classification (Critical, Error, Warning, Info)
• Support for all OAS versions (2.0, 3.0.x, 3.1.x, 3.2.x)
• Cross-version comparison with limitations

CLI Usage

# Simple semantic diff
oastools diff api-v1.yaml api-v2.yaml

# Breaking change detection with severity classification
oastools diff --breaking api-v1.yaml api-v2.yaml

# Exclude informational changes from output
oastools diff --breaking --no-info old.yaml new.yaml

# Works with URLs too
oastools diff https://example.com/api/v1.yaml https://example.com/api/v2.yaml

API Usage

import "github.com/erraggy/oastools/differ"

// Simple convenience function
result, err := differ.Diff("api-v1.yaml", "api-v2.yaml")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Found %d changes\n", len(result.Changes))

// Breaking change detection
d := differ.New()
d.Mode = differ.ModeBreaking
d.IncludeInfo = false

result, err := d.Diff("api-v1.yaml", "api-v2.yaml")
if result.HasBreakingChanges {
    fmt.Printf("⚠️  Found %d breaking changes\n", result.BreakingCount)
    os.Exit(1)
}

Change Detection Categories

The differ detects changes across all OAS elements:

• ✅ Endpoints (paths)
• ✅ Operations (HTTP methods)
• ✅ Parameters
• ✅ Request bodies
• ✅ Responses
• ✅ Schemas/definitions
• ✅ Security schemes
• ✅ Servers
• ✅ Metadata (info, contact, license, tags)

Breaking Change Classification

In breaking mode, changes are categorized by severity:

• Critical 🚨: Removed endpoints, operations, required parameters
• Error ❌: Incompatible type changes, removed enum values, removed success responses
• Warning ⚠️: Deprecated operations, server changes, added required fields
• Info ℹ️: Additions, relaxed constraints, documentation updates

Output Features

• Pretty-printed output with severity symbols (✗, ⚠, ℹ)
• Changes grouped by category in breaking mode
• Summary statistics (total, breaking, warnings, info)
• Exit code 1 when breaking changes are found (perfect for CI/CD)

Installation

Homebrew

brew tap erraggy/oastools
brew install oastools

Binary Download

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

Go Install

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

Related PRs

• #22 - feat(differ): add OpenAPI specification diff and breaking change detection

Technical Details

New Package:

• github.com/erraggy/oastools/differ - Public API for OpenAPI comparison

Implementation:

• differ/differ.go: Core types and API (266 lines)
• differ/simple.go: Simple semantic diff (742 lines)
• differ/breaking.go: Breaking change detection (814 lines)
• differ/doc.go: Package documentation (236 lines)
• differ/example_test.go: Runnable examples (154 lines)
• differ/differ_test.go: Comprehensive tests (300 lines)

Test Coverage:

• ✅ All existing tests pass
• ✅ Comprehensive unit tests for differ package
• ✅ Integration tests with real OAS examples
• ✅ Test fixtures: petstore-v1.yaml and petstore-v2.yaml

Documentation:

• ✅ Package-level godoc with examples
• ✅ CLI help text with usage examples
• ✅ Updated root package documentation
• ✅ Updated CLAUDE.md with differ package

Use Cases

Perfect for:

• 🔍 Reviewing API changes before deployment
• 🚨 Detecting breaking changes in CI/CD pipelines
• 📊 Generating changelogs between API versions
• ✅ Ensuring backward compatibility
• 📝 Documenting API evolution

Breaking Changes

None. This release is fully backward compatible.

Full Changelog

Full Changelog: v1.8.0...v1.9.0

v1.8.0

Summary

This release adds URL loading support for OpenAPI specifications and improves path validation with REST best practice warnings. It also modernizes the codebase to use current Go idioms (Go 1.18+ and 1.22+).

What's New

URL Loading Support

Load OpenAPI specifications directly from HTTP/HTTPS URLs in addition to local files:

# Validate specs from URLs
oastools validate https://example.com/api/openapi.yaml

# Parse from URLs
oastools parse https://petstore3.swagger.io/api/v3/openapi.json

# Convert specs from URLs
oastools convert -t 3.0.3 https://example.com/api/swagger.yaml -o openapi.yaml

Features:

• HTTP/HTTPS URL support for parse, validate, and convert commands
• Automatic format detection from URL extension or Content-Type header
• 30-second timeout for HTTP requests
• Version-aware User-Agent header (oastools/1.8.0)

Known Limitation: Relative $ref paths in URL-loaded specs resolve against the current directory, not relative to the URL.

Path Validation Improvements

Enhanced path validation with REST best practice warnings:

• Trailing slashes now generate warnings instead of errors (aligned with OAS spec)
• Comprehensive path validation catches malformed templates:
  • Consecutive slashes (//)
  • Reserved characters (#, ?)
  • Unclosed/unopened braces
  • Empty parameter names
  • Duplicate parameter names
  • Paths not starting with /

Example:

$ oastools validate api.yaml
...
Warnings (2):
  ⚠ paths./users/: Path has trailing slash, which is discouraged by REST best practices
    Spec: https://spec.openapis.org/oas/v3.0.3.html#paths-object

Code Modernization

Updated codebase to use modern Go idioms:

• interface{} → any: 233 replacements across 27 files (Go 1.18+)
• Modern for loops: Updated to use range over int syntax (Go 1.22+)

No functional changes—purely stylistic improvements for better readability.

Changes

Features

• parser: Add URL loading support with HTTP/HTTPS (#20)

  • New fetchURL() method with timeout and error handling
  • Format detection from URL extension and Content-Type header
  • User-Agent header with version information
  • Comprehensive test suite (46 tests for URL functionality)

• validator: Improve path validation (#21)

  • Change trailing slashes from errors to warnings
  • Add comprehensive path template validation (17 test cases)
  • Extract checkTrailingSlash() helper for DRY compliance
  • Update package documentation with path validation details

Refactoring

• codebase: Modernize Go code style (#21)
  • Replace interface{} with any (233 occurrences)
  • Update for loops to use range over int (3 loops)
  • No functional changes

Documentation

• README: Add URL loading examples and limitations
• validator: Document path validation and REST best practices
• planning: Remove completed documentation (code-style, goreleaser)

Technical Details

Compatibility:

• Go 1.24 required for range over int syntax
• All 465 tests passing
• No breaking changes to public APIs

Performance:

• URL loading adds ~200-500ms latency (network dependent)
• No impact on local file operations
• Same performance characteristics as v1.7.2 for parsing/validation

Installation

Homebrew (Recommended)

brew tap erraggy/oastools
brew install oastools

To upgrade from a previous version:

brew upgrade oastools

Binary Download

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

Available for:

• macOS (Intel and Apple Silicon)
• Linux (x86_64, ARM64, i386)
• Windows (x86_64, i386)

Go Install

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

Related PRs

• #20 - feat(parser): add URL loading support
• #21 - feat(validator): improve path validation and modernize Go code style

Full Changelog

v1.7.2...v1.8.0

v1.7.2

What's Fixed

This release fixes the version display issue. Running oastools -v now correctly shows:

oastools v1.7.2

Previously, binaries were showing an incorrect version number.

Homebrew Installation

brew tap erraggy/oastools
brew install oastools

Or upgrade if you already have it installed:

brew upgrade oastools

Other Installation Options

Pre-built binaries are available for:

• macOS (Intel and Apple Silicon)
• Linux (x86_64, ARM64, and i386)
• Windows (x86_64 and i386)

Download from the assets below.

---

Technical note: Version is now embedded at build time using ldflags, and binaries are ~15% smaller due to stripped debug symbols.

v1.7.1

Homebrew Installation Now Available! 🍺

You can now install oastools using Homebrew on macOS and Linux:

brew tap erraggy/oastools
brew install oastools

That's it! No manual downloads, no PATH configuration needed.

Updating

To update to future versions:

brew upgrade oastools

What is oastools?

oastools is a command-line tool for working with OpenAPI Specification files:

• Validate OpenAPI specs (2.0, 3.0.x, 3.1.x, 3.2.x)
• Parse and analyze OAS documents
• Convert between OAS versions (2.0 ↔ 3.x)
• Join multiple OpenAPI specs into one

Other Installation Options

Download Binaries

If you prefer not to use Homebrew, pre-built binaries are available for:

• macOS (Intel and Apple Silicon)
• Linux (x86_64, ARM64, and i386)
• Windows (x86_64 and i386)

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

Quick Start

After installation, try validating an OpenAPI spec:

oastools validate openapi.yaml

Or get help:

oastools --help

---

For developers: This release includes automated binary builds and Homebrew formula publishing via GoReleaser.

v1.7.0 - Performance improvements and benchmark infrastructure

Summary

This release establishes comprehensive performance benchmarking infrastructure and delivers significant JSON marshaling performance improvements. The v1.7.0 release focuses on measurable performance gains while maintaining full backward compatibility.

What's New

Benchmark Infrastructure (Phase 1)

• Comprehensive benchmark suite with 60+ benchmarks across all packages (parser, validator, converter, joiner)
• Benchmark test fixtures for small, medium, and large OpenAPI documents
• Baseline performance metrics captured for future comparison
• Integration with make bench commands for easy performance testing

JSON Marshaler Optimization (Phase 2)

• 25-32% faster JSON marshaling for structures with specification extensions
• 29-37% fewer memory allocations during marshaling operations
• Optimized all 29 custom JSON marshalers across 7 files
• More efficient handling of OpenAPI specification extensions (x-* fields)

Performance Improvements

Measured on Apple M4, darwin/arm64, Go 1.24:

Type	Time Improvement	Allocation Improvement
Info	26% faster (2,323ns → 1,707ns)	32% fewer (38 → 26 allocs)
Contact	32% faster (2,336ns → 1,599ns)	37% fewer (38 → 24 allocs)
Server	25% faster (2,837ns → 2,160ns)	29% fewer (41 → 29 allocs)

These improvements apply to all OpenAPI types with specification extensions, providing consistent performance gains across parser, validator, converter, and joiner operations.

Technical Details

Optimization Approach

Before (double-marshal pattern):

// 4 operations: marshal → unmarshal → modify → marshal
aux, _ := json.Marshal(struct)
var m map[string]interface{}
json.Unmarshal(aux, &m)
for k, v := range Extra { m[k] = v }
return json.Marshal(m)

After (direct map building):

// 2 operations: build map → marshal
m := make(map[string]interface{})
// Add fields directly to map
for k, v := range Extra { m[k] = v }
return json.Marshal(m)

Files Modified

• parser/common_json.go - 8 marshalers
• parser/paths_json.go - 7 marshalers
• parser/parameters_json.go - 4 marshalers
• parser/schema_json.go - 3 marshalers
• parser/security_json.go - 3 marshalers
• parser/oas2_json.go - 1 marshaler
• parser/oas3_json.go - 2 marshalers

Test Coverage

• All 403 existing tests pass
• No regressions in functionality
• JSON round-trip correctness maintained

Documentation

• Added planning/improve-performance.md documenting the complete performance improvement strategy
• Updated CLAUDE.md with comprehensive release process documentation
• Benchmark results saved to benchmark-baseline.txt and benchmark-20251117-193712.txt

Breaking Changes

None. This release is fully backward compatible with v1.6.x.

Related PRs

• #17 - feat(perf): establish Phase 1 benchmark infrastructure and baseline
• #18 - perf(parser): Phase 2 - JSON marshaler optimization (25-32% faster)

Migration Guide

No migration required. All changes are internal optimizations that maintain the same public API and behavior.

What's Next

Phase 3 optimizations are on hold pending real-world performance feedback. Additional low-risk optimizations are documented and available for future implementation if performance needs arise.

v1.6.1 - Fix JSON output field name casing

Summary

This patch release fixes a critical bug where JSON output had incorrect field name casing (e.g., OpenAPI instead of openapi), violating the OpenAPI Specification.

Changes

Bug Fixes

• JSON Field Casing: Added JSON struct tags to all parser types to ensure correct field name casing in JSON output
• Custom JSON Marshalers: Implemented custom MarshalJSON/UnmarshalJSON methods for all types with Extra fields to properly inline specification extensions (x-* fields)
• Error Handling: Fixed Responses.UnmarshalJSON to return errors for invalid status codes instead of silently dropping them

Improvements

• Test Coverage: Added 17 comprehensive test functions covering field casing, Extra field handling, error cases, edge scenarios, and performance
• Documentation: Added godoc comments to all custom JSON marshalers explaining their purpose and behavior
• Code Quality: Enhanced error messages to provide better context for validation failures

Breaking Changes

None - this is a backward-compatible bug fix.

Technical Details

The fix involved:

1. Adding json tags to all struct fields across 7 parser files
2. Creating 6 new files with custom JSON marshalers for 20+ types
3. Implementing proper Extra field flattening using type alias pattern
4. Adding comprehensive test coverage for JSON marshaling/unmarshaling

All changes ensure strict compliance with OpenAPI Specification field naming requirements.