# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview Go monorepo of utility libraries for the `go-openapi` / `go-swagger` ecosystem. The root package is a **backward-compat facade** — all its exported functions are deprecated and delegate to sub-packages. See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details. ## Workspace & Modules Go workspace (`go.work`, Go 1.24). Contains 15+ modules: | Module | Purpose | |--------|---------| | `.` (root) | Deprecated shims forwarding to sub-packages | | `cmdutils` | CLI utility helpers | | `conv` | Type conversions: string-to-value, value-to-pointer, pointer-to-value (generics) | | `fileutils` | File and path utilities | | `jsonname` | Infer JSON field names from Go struct tags | | `jsonutils` | JSON read/write, `ConcatJSON`, `JSONMapSlice`; pluggable adapter system | | `jsonutils/adapters/easyjson` | easyjson adapter (separate module to isolate dependency) | | `loading` | Load specs from filesystem or HTTP | | `mangling` | Name mangling: `ToGoName`, `ToFileName`, `ToVarName`, etc.; configurable initialisms | | `netutils` | Host/port parsing | | `stringutils` | Slice search, query parameter splitting | | `typeutils` | Zero-value and nil-safe interface checks | | `yamlutils` | YAML-to-JSON conversion, ordered YAML documents | Inter-module dependencies use `replace` directives pointing to local paths. ## Testing ```sh # Run all tests across every workspace module go test work ./... # Run tests for a single module go test ./conv/... ``` Note: plain `go test ./...` only tests the root module. The `work` pattern expands to all modules listed in `go.work`. CI runs tests on `{ubuntu, macos, windows} x {stable, oldstable}` with `-race` via `gotestsum`. ### Fuzz tests ```sh # List all fuzz targets across the workspace go test work -list Fuzz ./... # Run a specific fuzz target (go test -fuzz cannot span multiple packages) go test -fuzz=Fuzz -run='FuzzToGoName$' -fuzztime=1m30s ./mangling ``` Fuzz corpus lives in `testdata/fuzz/` within each package. CI runs each fuzz target for 1m30s with a 5m minimize timeout. ### Test framework `github.com/go-openapi/testify/v2` — a zero-dep fork of `stretchr/testify`. Because it's a fork, `testifylint` does not work. Patterns: table-driven tests with `t.Run`, fuzz tests, benchmarks, and integration tests in `jsonutils/adapters/testintegration/`. ## Linting ```sh golangci-lint run ``` Config: `.golangci.yml` — posture is `default: all` with explicit disables. See [docs/STYLE.md](../docs/STYLE.md) for the rationale behind each disabled linter. Key rules: - Every `//nolint` directive **must** have an inline comment explaining why. - Prefer disabling a linter over scattering `//nolint` across the codebase. ## Code Conventions - All files must have SPDX license headers (Apache-2.0). - Go version policy: support the 2 latest stable Go minor versions. - Commits require DCO sign-off (`git commit -s`). - Root-level `*_iface.go` files are thin deprecated wrappers — do not add new public API there. - `jsonutils` uses a pluggable adapter registry (`adapters.Registry`); new JSON backends should be separate modules implementing interfaces from `jsonutils/adapters/ifaces`. - `mangling.NameMangler` is configured via functional options and is concurrency-safe.