Add CLAUDE.md for Claude Code guidance

CLAUDE.md

@@ -0,0 +1,75 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## What This Project Does
+
+SwaggerSwift is a Swift code generator that converts Swagger (OpenAPI 2.0) specifications into a fully-typed, async/await-ready Swift networking layer. It downloads specs from GitHub and generates Swift packages with API clients, data models, and shared utilities.
+
+## Commands
+
+```bash
+# Build
+swift build -c release
+# Binary: .build/release/swaggerswift
+
+# Run tests
+swift test --parallel
+
+# Run a single test
+swift test --filter SwaggerSwiftMLTests.ParserTests/testSomething
+
+# Run the generator locally
+export GITHUB_TOKEN="ghp_…"
+.build/release/swaggerswift --swagger-file-path ./SwaggerFile.yml --verbose
+```
+
+Code style is enforced by `swift-format` (`.swift-format` config): 120-char line limit, 4-space indentation.
+
+## Architecture
+
+Three targets in `Package.swift`:
+
+**`SwaggerSwiftML`** — Parsing layer. Defines all Swagger data model types (`Operation`, `Parameter`, `Schema`, `Response`, etc.) and parses JSON/YAML specs via Yams. Produces an in-memory Swagger AST.
+
+**`SwaggerSwiftCore`** — Code generation engine. Takes the parsed AST and produces Swift source files via Stencil templates. Key components:
+- `Generator` — Main orchestrator; reads `SwaggerFile.yml`, downloads specs from GitHub, and drives the pipeline
+- `ModelTypeResolver` — Maps Swagger types (primitives, enums, arrays, objects, `$ref`) to Swift types
+- `APIRequestFactory` / `APIResponseTypeFactory` — Build async API client methods from `Operation` nodes
+- `TemplateRenderer` — Renders Stencil templates from `Sources/SwaggerSwiftCore/Templates/`
+
+**`SwaggerSwift`** (executable) — Thin CLI wrapper using swift-argument-parser. Entry point: `MyMain.swift`.
+
+### Data Flow
+
+```
+SwaggerFile.yml → Generator → GitHub API (downloads specs)
+                           → SwaggerParser (SwaggerSwiftML)
+                           → ModelTypeResolver → ObjectModelFactory
+                           → APIRequestFactory → TemplateRenderer (Stencil)
+                           → FileWriter → Generated Swift Package
+```
+
+### Generated Output Structure
+
+```
+Generated/
+└── MyAPI/
+    ├── Package.swift
+    └── Sources/
+        ├── MyAPIShared/          # Shared networking utilities (templates)
+        └── UserService/          # One target per service
+            ├── UserServiceClient.swift
+            └── Models/
+```
+
+### Template System
+
+Stencil templates live in `Sources/SwaggerSwiftCore/Templates/`. Each template maps to a generated file type (API client, model struct, enum, typealias, shared library files). Templates are loaded from the bundle at runtime — the `Dockerfile` copies them explicitly.
+
+### Testing
+
+- `SwaggerSwiftMLTests` — Unit tests for parsing; uses YAML/JSON fixtures in `Tests/SwaggerSwiftMLTests/TestResources/`
+- `SwaggerSwiftCoreTests` — Unit tests for code generation; includes golden file (snapshot) tests
+
+CI runs on both macOS (Xcode 26.2) and Linux (Swift 6.0) via `.github/workflows/build_and_test.yml`.