oastools: Instructions file for Codex

AGENTS.md

This file provides quick, actionable guidance for AI coding agents working on the oastools project. For comprehensive details, see CLAUDE.md.

⚠️ BRANCH PROTECTION: The main branch has push protections. Before making ANY changes, verify you're on a feature branch (git branch --show-current). If on main, create a branch first: git checkout -b <type>/<description>

Project Overview

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.25+

Dev Environment Setup

CRITICAL: Install the pinned golangci-lint before making code changes:

make lint-install
export PATH=$PATH:$(go env GOPATH)/bin

The version lives in one place, GOLANGCI_VERSION in the Makefile, and CI reads it from there. make lint refuses to run against any other version, because findings would not match CI.

Quick Commands

# Build and test workflow (run after every code change)
make check          # Runs tidy, fmt, lint, test, and git status

# Individual commands
make build          # Build binary to bin/oastools
make test           # Run all tests with cross-package coverage
make test-coverage  # Generate and view HTML coverage report
make fmt            # Format all Go code
make lint           # Run golangci-lint (the version the Makefile pins)

# Benchmarks
make bench          # Run benchmarks
make bench-save     # Save new benchmark baseline (only if changes affect performance)

Testing Requirements

ALL exported functionality MUST have comprehensive tests:

• Positive cases (valid inputs work)
• Negative cases (errors handled correctly)
• Edge cases (nil, empty, boundary conditions)
• Integration cases (components work together)

Benchmark tests MUST use Go 1.24+ pattern:

func BenchmarkOperation(b *testing.B) {
    // Setup
    source, _ := parser.ParseWithOptions(...)
    
    for b.Loop() {  // ✅ Use b.Loop(), NOT for i := 0; i < b.N; i++
        _, err := Operation(source)
        if err != nil {
            b.Fatal(err)
        }
    }
}