feat!: introduce comprehensive OpenAPI 3.0.x/3.1.x parser with validation, walking, and upgrading

Author: TristanSpeakEasy

.github/workflows/test.yaml

@@ -7,57 +7,77 @@ on:
     branches: [main]
 
 jobs:
-  test-and-build:
+  lint:
+    name: Lint and Format Check
     runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install mise
+        uses: jdx/mise-action@v2
+
+      - name: Check code formatting
+        run: mise run fmt-check
+
+      - name: Check module dependencies
+        run: mise run mod-check
+
+      - name: Run lint task
+        run: mise run lint
+
+      - name: Check examples are up to date
+        run: mise run examples-check
+
+  test-and-build:
+    name: Test and Build
+    needs: lint
+    strategy:
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
     permissions:
       contents: read
       pull-requests: write
 
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Go
-        uses: actions/setup-go@v5
-        with:
-          go-version: "1.23"
-
-      - name: Install dependencies
-        run: go mod download
-
-      - name: Run golangci-lint
-        uses: golangci/golangci-lint-action@v6
-        with:
-          version: latest
+      - name: Install mise
+        uses: jdx/mise-action@v2
 
       - name: Run tests with coverage
-        run: |
-          go test -v -race -coverprofile=coverage.out -covermode=atomic ./...
-          go tool cover -html=coverage.out -o coverage.html
+        if: matrix.os == 'ubuntu-latest'
+        run: mise run test-coverage
+
+      - name: Run tests (Windows)
+        if: matrix.os == 'windows-latest'
+        run: mise run test
 
       - name: Calculate coverage
+        if: matrix.os == 'ubuntu-latest'
         id: coverage
         run: |
           COVERAGE=$(go tool cover -func=coverage.out | grep total | awk '{print $3}')
           echo "coverage=$COVERAGE" >> $GITHUB_OUTPUT
           echo "Coverage: $COVERAGE"
 
       - name: Get main branch coverage
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request' && matrix.os == 'ubuntu-latest'
         id: main-coverage
         run: |
           # Store current working directory
           CURRENT_DIR=$(pwd)
-          
+
           # Fetch main branch
           git fetch origin main:main
-          
+
           # Checkout main branch in a temporary directory
           git worktree add /tmp/main-branch main
-          
+
           # Run tests on main branch to get coverage
           cd /tmp/main-branch
           go test -coverprofile=main-coverage.out -covermode=atomic ./... > /dev/null 2>&1 || echo "Main branch tests failed"
-          
+
           if [ -f main-coverage.out ]; then
             MAIN_COVERAGE=$(go tool cover -func=main-coverage.out | grep total | awk '{print $3}' || echo "0.0%")
             echo "main-coverage=$MAIN_COVERAGE" >> $GITHUB_OUTPUT
@@ -69,23 +89,24 @@ jobs:
             echo "main-coverage=0.0%" >> $GITHUB_OUTPUT
             echo "Could not get main branch coverage"
           fi
-          
+
           # Return to original directory
           cd "$CURRENT_DIR"
-          
+
           # Clean up worktree (force removal to handle modified files)
           git worktree remove --force /tmp/main-branch || rm -rf /tmp/main-branch
 
       - name: Generate coverage summary
+        if: matrix.os == 'ubuntu-latest'
         id: coverage-summary
         run: |
           echo "## 📊 Test Coverage Report" > coverage-summary.md
           echo "" >> coverage-summary.md
-          
+
           # Current coverage
           CURRENT_COV="${{ steps.coverage.outputs.coverage }}"
           echo "**Current Coverage:** \`$CURRENT_COV\`" >> coverage-summary.md
-          
+
           # Compare with main if this is a PR
           if [ "${{ github.event_name }}" = "pull_request" ] && [ "${{ steps.main-coverage.outputs.main-coverage }}" != "" ]; then
             MAIN_COV="${{ steps.main-coverage.outputs.main-coverage }}"
@@ -109,7 +130,7 @@ jobs:
               fi
             fi
           fi
-          
+
           echo "" >> coverage-summary.md
           echo "### Coverage by Package" >> coverage-summary.md
           echo "\`\`\`" >> coverage-summary.md
@@ -122,25 +143,25 @@ jobs:
           echo "_Generated by GitHub Actions_" >> coverage-summary.md
 
       - name: Comment PR with coverage
-        if: github.event_name == 'pull_request'
+        if: github.event_name == 'pull_request' && matrix.os == 'ubuntu-latest'
         uses: actions/github-script@v7
         with:
           script: |
             const fs = require('fs');
             const coverageSummary = fs.readFileSync('coverage-summary.md', 'utf8');
-            
+
             // Look for existing coverage comment
             const comments = await github.rest.issues.listComments({
               issue_number: context.issue.number,
               owner: context.repo.owner,
               repo: context.repo.repo,
             });
-            
+
             const botComment = comments.data.find(comment => 
               comment.user.type === 'Bot' && 
               comment.body.includes('📊 Test Coverage Report')
             );
-            
+
             if (botComment) {
               // Update existing comment
               await github.rest.issues.updateComment({
@@ -160,12 +181,13 @@ jobs:
             }
 
       - name: Upload coverage artifact
+        if: matrix.os == 'ubuntu-latest'
         uses: actions/upload-artifact@v4
         with:
           name: coverage-report
           path: |
             coverage.out
             coverage.html
 
-      - name: Build
-        run: go build -v ./...
+      - name: Build (${{ matrix.os }})
+        run: mise run build

.gitignore

@@ -0,0 +1,7 @@
+# Coverage files generated by test-coverage task
+coverage.out
+coverage.html
+
+# VSCode settings (user-specific)
+.vscode/*
+!.vscode/settings.example.json

.golangci.yaml

@@ -0,0 +1,9 @@
+version: "2"
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0
+
+linters:
+  enable:
+    - govet
+    - paralleltest

.mise.toml

@@ -0,0 +1,17 @@
+[tools]
+go = "1.24.3"
+golangci-lint = "2.1.1"
+gotestsum = "latest"
+
+[tasks.setup-vscode-symlinks]
+description = "Create VSCode symlinks for tools not automatically handled by mise-vscode"
+run = [
+    "mkdir -p .vscode/mise-tools",
+    "ln -sf $(mise exec [email protected] -- which golangci-lint) .vscode/mise-tools/golangci-lint",
+]
+
+[hooks]
+postinstall = [
+    "mise run setup-vscode-symlinks",
+    "go install go.uber.org/nilaway/cmd/nilaway@8ad05f0",
+]

.vscode/settings.example.json

@@ -0,0 +1,16 @@
+{
+  "mise.configureExtensionsUseSymLinks": true,
+  "go.goroot": "${workspaceFolder}/.vscode/mise-tools/goRoot",
+  "go.alternateTools": {
+    "go": "${workspaceFolder}/.vscode/mise-tools/go",
+    "dlv": "${workspaceFolder}/.vscode/mise-tools/dlv",
+    "gopls": "${workspaceFolder}/.vscode/mise-tools/gopls",
+    "golangci-lint": "${workspaceFolder}/.vscode/mise-tools/golangci-lint",
+    "customFormatter": "${workspaceFolder}/.vscode/mise-tools/golangci-lint"
+  },
+  "go.lintTool": "golangci-lint",
+  "go.lintFlags": ["--path-mode=abs", "--fast-only"],
+  "go.formatTool": "custom",
+  "go.formatFlags": ["fmt", "--stdin"],
+  "go.lintOnSave": "package"
+}

README.md

@@ -38,6 +38,10 @@
 
 The `arazzo` package provides an API for working with Arazzo documents including reading, creating, mutating, walking and validating them.
 
+### [openapi](./openapi)
+
+The `openapi` package provides an API for working with OpenAPI documents including reading, creating, mutating, walking, validating and upgrading them. Supports both OpenAPI 3.0.x and 3.1.x specifications.
+
 ## Sub Packages
 
 This repository also contains a number of sub packages that are used by the main packages to provide the required functionality. The below packages may be moved into their own repository in the future, depending on future needs.