AGENTS.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Documentation
6 
7You can find the complete documentation for this project in the `docs/` directory. It describes the architecture, build system, development practices and more in detail the the project.
8 
9There is also a minimal, LLM-friendly version of the documentation in `README-LLM.md`. You can refer to the file if you need a quick overview of the project without going through the entire documentation.
10 
11## Build and Development Commands
12 
13### Primary Build System
14This project uses **Fastlane** for primary build automation. Key commands:
15 
16```bash
17# Install dependencies
18bundle install
19 
20# Run all tests across platforms (iOS, macOS, tvOS, watchOS)
21bundle exec fastlane tests
22 
23# Run specific platform tests
24bundle exec fastlane test destination:"platform=iOS Simulator,name=iPhone 16"
25 
26# Build for specific platform
27bundle exec fastlane build destination:"platform=iOS Simulator,name=iPhone 16"
28 
29# Lint CocoaPods spec and Swift Package Manager
30bundle exec fastlane lint
31```
32 
33### Release Process
34```bash
35# Full release workflow (tests, linting, versioning, GitHub release, CocoaPods push)
36bundle exec fastlane release version:X.X.X
37```
38 
39## Architecture Overview
40 
41@docs/architecture.md
42 
43Kingfisher is a modular image loading and caching library with clear separation of concerns:
44 
45### Core Components Flow
461. **KingfisherManager** (`Sources/General/KingfisherManager.swift`) - Central coordinator
472. **ImageDownloader** (`Sources/Networking/ImageDownloader.swift`) - Network layer
483. **ImageCache** (`Sources/Cache/ImageCache.swift`) - Dual-layer caching (memory + disk)
494. **ImageProcessor** (`Sources/Image/ImageProcessor.swift`) - Image transformation pipeline
50 
51### Key Architectural Patterns
52- **Protocol-oriented design** with `KingfisherCompatible` protocol
53- **Namespace wrapper pattern** - All functionality accessed via `.kf` property
54- **Builder pattern** - `KF.url()...` method chaining
55- **Options pattern** - `KingfisherOptionsInfo` for configuration
56 
57### Module Structure
58```
59Sources/
60├── General/           # Core managers, options, data providers
61├── Networking/        # Download, prefetch, session management  
62├── Cache/            # Multi-layer caching system
63├── Image/            # Processing, filters, formats, transitions
64├── Extensions/       # UIKit/AppKit/SwiftUI integration
65├── SwiftUI/         # SwiftUI-specific components
66├── Utility/         # Helper utilities and extensions
67└── Views/           # Custom UI components
68```
69 
70### Integration Points
71- **UIKit**: Extensions for `UIImageView`, `UIButton` via `.kf` namespace
72- **SwiftUI**: `KFImage` and `KFAnimatedImage` components
73- **Cross-platform**: Extensive conditional compilation for iOS/macOS/tvOS/watchOS/visionOS
74 
75## Platform Support
76- **UIKit/AppKit**: iOS 13.0+ / macOS 10.15+ / tvOS 13.0+ / watchOS 6.0+ / visionOS 1.0+
77- **SwiftUI**: iOS 14.0+ / macOS 11.0+ / tvOS 14.0+ / watchOS 7.0+ / visionOS 1.0+
78- **Swift**: 5.9+ (with Swift 6 strict concurrency support)
79 
80## Testing
81 
82### Test Structure
83- **Location**: `Tests/KingfisherTests/`
84- **Framework**: XCTest with custom `KingfisherTestHelper`
85- **Network mocking**: Uses Nocilla dependency for HTTP stubbing
86- **Test assets**: `dancing-banana.gif`, `single-frame.gif`
87 
88### Running Tests
89```bash
90# All platforms (preferred)
91bundle exec fastlane tests
92 
93# Single platform via destination
94bundle exec fastlane test destination:"platform=iOS Simulator,name=iPhone 15"
95```
96 
97## Documentation System
98 
99Provides a DocC-based documentation for framework users:
100 
101- **DocC integration** with comprehensive tutorials and API docs
102- **Location**: `Sources/Documentation.docc/`
103- **Online**: Swift Package Index hosted documentation
104- **Tutorials**: Both UIKit and SwiftUI getting started guides available