| 1 |
# CLAUDE.md |
| 2 |
|
| 3 |
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 |
|
| 5 |
## Project Overview |
| 6 |
|
| 7 |
Go monorepo of utility libraries for the `go-openapi` / `go-swagger` ecosystem. The root package |
| 8 |
is a **backward-compat facade** — all its exported functions are deprecated and delegate to sub-packages. |
| 9 |
|
| 10 |
See [docs/MAINTAINERS.md](../docs/MAINTAINERS.md) for CI/CD, release process, and repo structure details. |
| 11 |
|
| 12 |
## Workspace & Modules |
| 13 |
|
| 14 |
Go workspace (`go.work`, Go 1.24). Contains 15+ modules: |
| 15 |
|
| 16 |
| Module | Purpose | |
| 17 |
|--------|---------| |
| 18 |
| `.` (root) | Deprecated shims forwarding to sub-packages | |
| 19 |
| `cmdutils` | CLI utility helpers | |
| 20 |
| `conv` | Type conversions: string-to-value, value-to-pointer, pointer-to-value (generics) | |
| 21 |
| `fileutils` | File and path utilities | |
| 22 |
| `jsonname` | Infer JSON field names from Go struct tags | |
| 23 |
| `jsonutils` | JSON read/write, `ConcatJSON`, `JSONMapSlice`; pluggable adapter system | |
| 24 |
| `jsonutils/adapters/easyjson` | easyjson adapter (separate module to isolate dependency) | |
| 25 |
| `loading` | Load specs from filesystem or HTTP | |
| 26 |
| `mangling` | Name mangling: `ToGoName`, `ToFileName`, `ToVarName`, etc.; configurable initialisms | |
| 27 |
| `netutils` | Host/port parsing | |
| 28 |
| `stringutils` | Slice search, query parameter splitting | |
| 29 |
| `typeutils` | Zero-value and nil-safe interface checks | |
| 30 |
| `yamlutils` | YAML-to-JSON conversion, ordered YAML documents | |
| 31 |
|
| 32 |
Inter-module dependencies use `replace` directives pointing to local paths. |
| 33 |
|
| 34 |
## Testing |
| 35 |
|
| 36 |
```sh |
| 37 |
# Run all tests across every workspace module |
| 38 |
go test work ./... |
| 39 |
|
| 40 |
# Run tests for a single module |
| 41 |
go test ./conv/... |
| 42 |
``` |
| 43 |
|
| 44 |
Note: plain `go test ./...` only tests the root module. The `work` pattern expands to all |
| 45 |
modules listed in `go.work`. |
| 46 |
|
| 47 |
CI runs tests on `{ubuntu, macos, windows} x {stable, oldstable}` with `-race` via `gotestsum`. |
| 48 |
|
| 49 |
### Fuzz tests |
| 50 |
|
| 51 |
```sh |
| 52 |
# List all fuzz targets across the workspace |
| 53 |
go test work -list Fuzz ./... |
| 54 |
|
| 55 |
# Run a specific fuzz target (go test -fuzz cannot span multiple packages) |
| 56 |
go test -fuzz=Fuzz -run='FuzzToGoName$' -fuzztime=1m30s ./mangling |
| 57 |
``` |
| 58 |
|
| 59 |
Fuzz corpus lives in `testdata/fuzz/` within each package. CI runs each fuzz target for 1m30s |
| 60 |
with a 5m minimize timeout. |
| 61 |
|
| 62 |
### Test framework |
| 63 |
|
| 64 |
`github.com/go-openapi/testify/v2` — a zero-dep fork of `stretchr/testify`. |
| 65 |
Because it's a fork, `testifylint` does not work. |
| 66 |
|
| 67 |
Patterns: table-driven tests with `t.Run`, fuzz tests, benchmarks, and integration |
| 68 |
tests in `jsonutils/adapters/testintegration/`. |
| 69 |
|
| 70 |
## Linting |
| 71 |
|
| 72 |
```sh |
| 73 |
golangci-lint run |
| 74 |
``` |
| 75 |
|
| 76 |
Config: `.golangci.yml` — posture is `default: all` with explicit disables. |
| 77 |
See [docs/STYLE.md](../docs/STYLE.md) for the rationale behind each disabled linter. |
| 78 |
|
| 79 |
Key rules: |
| 80 |
- Every `//nolint` directive **must** have an inline comment explaining why. |
| 81 |
- Prefer disabling a linter over scattering `//nolint` across the codebase. |
| 82 |
|
| 83 |
## Code Conventions |
| 84 |
|
| 85 |
- All files must have SPDX license headers (Apache-2.0). |
| 86 |
- Go version policy: support the 2 latest stable Go minor versions. |
| 87 |
- Commits require DCO sign-off (`git commit -s`). |
| 88 |
- Root-level `*_iface.go` files are thin deprecated wrappers — do not add new public API there. |
| 89 |
- `jsonutils` uses a pluggable adapter registry (`adapters.Registry`); new JSON backends |
| 90 |
should be separate modules implementing interfaces from `jsonutils/adapters/ifaces`. |
| 91 |
- `mangling.NameMangler` is configured via functional options and is concurrency-safe. |