|
| 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 | +SwiftkubeModel is a zero-dependency Swift package providing Codable, Hashable, Sendable model structs for all Kubernetes API objects. Currently tracks Kubernetes v1.33.3. |
| 8 | + |
| 9 | +## Build & Test Commands |
| 10 | + |
| 11 | +```bash |
| 12 | +swift build # Build the package |
| 13 | +swift test # Run all tests |
| 14 | +swift test --filter SwiftkubeModelTests.GroupVersionKindTests # Run a single test class |
| 15 | +swift format -i Sources/ Tests/ # Format code |
| 16 | +``` |
| 17 | + |
| 18 | +## Architecture |
| 19 | + |
| 20 | +### Code Generation |
| 21 | + |
| 22 | +Most files under `Sources/Model/` are **generated** by an external tool called `Swiftkube:ModelGen` (not in this repo). Generated files have this header comment: |
| 23 | +``` |
| 24 | +// Generated by Swiftkube:ModelGen |
| 25 | +// Kubernetes v1.33.3 |
| 26 | +``` |
| 27 | +Do not manually edit generated files unless you understand they will be overwritten on the next generation run. |
| 28 | + |
| 29 | +### Source Layout |
| 30 | + |
| 31 | +- **`Sources/Model/<group>/<version>/`** — Generated Kubernetes API structs, one file per type. Files follow the naming convention `TypeName+group.version.swift` (e.g., `Pod+core.v1.swift`). Each API group is a Swift namespace enum (e.g., `core.v1`, `apps.v1`, `networking.v1beta1`). |
| 32 | + |
| 33 | +- **`Sources/Model/`** (top-level files) — Core infrastructure: |
| 34 | + - `KubernetesResource.swift` — Protocol hierarchy: `KubernetesResource` → `MetadataHavingResource` → `KubernetesAPIResource`, plus capability marker protocols (`NamespacedResource`, `ClusterScopedResource`, `ReadableResource`, `ListableResource`, `CreatableResource`, `DeletableResource`, etc.) |
| 35 | + - `GroupVersionKind.swift` / `GroupVersionResource.swift` — GVK/GVR types and their lookup tables (`+DefaultResources`, `+KubernetesAPIResource`, `+Meta`, `+ResourceName`) |
| 36 | + - `UnstructuredResource.swift` — Type-erased resource for unknown/CRD types |
| 37 | + - `IntOrString.swift`, `Quantity.swift`, `JSONObject.swift` — Special Kubernetes types |
| 38 | + |
| 39 | +- **`Sources/Builders/`** — Closure-based builder functions under the `sk` namespace enum. Only covers common types (core/v1, apps/v1, meta/v1). |
| 40 | + |
| 41 | +- **`Sources/Codable/`** — Custom encoding/decoding support (`Any+Codable.swift`, `NullWrapper.swift`). |
| 42 | + |
| 43 | +- **`Sources/Extensions/`** — Convenience extensions on model types and `Hashes.swift` for Hashable conformance. |
| 44 | + |
| 45 | +### Key Patterns |
| 46 | + |
| 47 | +- All resources are `Codable`, `Hashable`, and `Sendable` structs. |
| 48 | +- API resources use `var` properties (not `let`) for mutability. |
| 49 | +- `apiVersion` and `kind` are `let` constants with default values on each API resource struct. |
| 50 | +- Resources with `JSONObject` fields (dictionary-backed) store values as `Dictionary<String, any Sendable>`. |
| 51 | +- The `sk` enum provides builder functions that use `inout` closure patterns via the internal `build(_:with:)` helper. |
0 commit comments