Debian Codegraph @

.claude/CLAUDE.md

raw
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.