@hivehub/rulebook 1.2.0

package/templates/languages/SWIFT.md

@@ -0,0 +1,466 @@
+<!-- SWIFT:START -->
+# Swift Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+swiftlint                  # Linting
+swift build                # Build verification
+swift test                 # All tests (100% pass)
+swift test --enable-code-coverage  # Coverage
+
+# Security audit:
+# (Use dependency scanning tools as needed)
+```
+
+## Swift Configuration
+
+**CRITICAL**: Use Swift 5.10+ with strict concurrency checking.
+
+- **Version**: Swift 5.10+
+- **Platform**: iOS 17+, macOS 14+
+- **Concurrency**: Enabled
+- **Warnings as Errors**: true
+
+### Package.swift Requirements
+
+```swift
+// swift-tools-version: 5.10
+import PackageDescription
+
+let package = Package(
+    name: "YourPackage",
+    platforms: [
+        .iOS(.v17),
+        .macOS(.v14),
+        .watchOS(.v10),
+        .tvOS(.v17)
+    ],
+    products: [
+        .library(
+            name: "YourPackage",
+            targets: ["YourPackage"]
+        ),
+    ],
+    dependencies: [],
+    targets: [
+        .target(
+            name: "YourPackage",
+            dependencies: [],
+            swiftSettings: [
+                .enableUpcomingFeature("StrictConcurrency"),
+                .enableUpcomingFeature("BareSlashRegexLiterals"),
+                .enableExperimentalFeature("StrictConcurrency=complete")
+            ]
+        ),
+        .testTarget(
+            name: "YourPackageTests",
+            dependencies: ["YourPackage"]
+        ),
+    ]
+)
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Format check (matches workflow - use lint mode, not --in-place!)
+swift-format lint --recursive Sources Tests
+
+# 2. Lint (matches workflow)
+swiftlint lint --strict
+
+# 3. Build (MUST pass with no warnings - matches workflow)
+swift build -Xswiftc -warnings-as-errors
+
+# 4. Run all tests (MUST pass 100% - matches workflow)
+swift test --enable-code-coverage
+
+# 5. Generate documentation (matches workflow)
+swift package generate-documentation
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- CI/CD failures happen when local commands differ from workflows
+- Example: Using `swift-format --in-place` locally but `lint` in CI = failure
+- Example: Missing `--enable-code-coverage` = CI coverage failures
+
+### Code Style
+
+Use SwiftLint for code style. Configuration in `.swiftlint.yml`:
+
+```yaml
+disabled_rules:
+  - trailing_whitespace
+
+opt_in_rules:
+  - empty_count
+  - explicit_init
+  - first_where
+  - closure_spacing
+  - overridden_super_call
+  - redundant_nil_coalescing
+  - private_outlet
+  - nimble_operator
+  - attributes
+  - operator_usage_whitespace
+  - closure_end_indentation
+  - literal_expression_end_indentation
+
+included:
+  - Sources
+  - Tests
+
+excluded:
+  - .build
+  - .swiftpm
+  - DerivedData
+
+line_length:
+  warning: 120
+  error: 140
+  ignores_comments: true
+
+type_body_length:
+  warning: 300
+  error: 400
+
+file_length:
+  warning: 500
+  error: 800
+
+function_body_length:
+  warning: 40
+  error: 60
+
+identifier_name:
+  min_length:
+    warning: 2
+  max_length:
+    warning: 50
+    error: 60
+
+custom_rules:
+  no_hardcoded_strings:
+    name: "No Hardcoded Strings"
+    regex: '(print|NSLog)\("'
+    message: "Use localized strings instead of hardcoded strings"
+    severity: warning
+```
+
+### Testing
+
+- **Framework**: XCTest (built-in)
+- **Location**: `Tests/` directory
+- **Async**: Use async/await in tests
+- **Coverage**: xcodebuild or swift-testing
+
+Example test:
+
+```swift
+import XCTest
+@testable import YourPackage
+
+final class YourPackageTests: XCTestCase {
+    func testProcessValidInput() async throws {
+        let processor = DataProcessor()
+        let result = try await processor.process("hello")
+        
+        XCTAssertEqual(result, "HELLO")
+    }
+    
+    func testProcessEmptyInputThrowsError() async {
+        let processor = DataProcessor()
+        
+        await XCTAssertThrowsError(try await processor.process("")) { error in
+            XCTAssertEqual(error as? ProcessorError, .emptyInput)
+        }
+    }
+    
+    func testPerformanceExample() {
+        let processor = DataProcessor()
+        
+        measure {
+            _ = try? processor.processSync("test")
+        }
+    }
+}
+
+// Helper extension for async testing
+extension XCTestCase {
+    func XCTAssertThrowsError<T>(
+        _ expression: @autoclosure () async throws -> T,
+        _ errorHandler: (Error) -> Void
+    ) async {
+        do {
+            _ = try await expression()
+            XCTFail("Should have thrown an error")
+        } catch {
+            errorHandler(error)
+        }
+    }
+}
+```
+
+### Documentation
+
+- Use Swift DocC for documentation
+- Document all public APIs with `///`
+- Include examples and parameters
+
+Example:
+
+```swift
+/// A processor that transforms input data.
+///
+/// Use this class to process strings and perform transformations.
+/// The processor supports both synchronous and asynchronous operations.
+///
+/// ## Usage
+///
+/// ```swift
+/// let processor = DataProcessor()
+/// let result = try await processor.process("hello")
+/// print(result) // Prints: HELLO
+/// ```
+public final class DataProcessor: Sendable {
+    
+    /// Creates a new data processor.
+    public init() {}
+    
+    /// Processes the input string asynchronously.
+    ///
+    /// This method transforms the input by converting it to uppercase.
+    ///
+    /// - Parameter input: The string to process. Must not be empty.
+    /// - Returns: The processed string in uppercase.
+    /// - Throws: `ProcessorError.emptyInput` if the input is empty.
+    ///
+    /// ## Example
+    ///
+    /// ```swift
+    /// let processor = DataProcessor()
+    /// let result = try await processor.process("hello")
+    /// // result is "HELLO"
+    /// ```
+    public func process(_ input: String) async throws -> String {
+        guard !input.isEmpty else {
+            throw ProcessorError.emptyInput
+        }
+        
+        return input.uppercased()
+    }
+}
+
+/// Errors that can occur during processing.
+public enum ProcessorError: Error, Sendable {
+    /// The input string was empty.
+    case emptyInput
+    /// An invalid format was encountered.
+    case invalidFormat(String)
+}
+```
+
+### Concurrency
+
+- Use `async`/`await` for asynchronous code
+- Mark types as `Sendable` when thread-safe
+- Use actors for state synchronization
+- Enable strict concurrency checking
+
+Example:
+
+```swift
+/// An actor that manages user data safely across concurrent access.
+public actor UserManager {
+    private var users: [String: User] = [:]
+    
+    /// Adds or updates a user.
+    public func setUser(_ user: User, for id: String) {
+        users[id] = user
+    }
+    
+    /// Retrieves a user by ID.
+    public func getUser(for id: String) -> User? {
+        users[id]
+    }
+}
+
+/// A thread-safe data structure.
+public struct User: Sendable {
+    public let id: String
+    public let name: String
+    public let email: String
+    
+    public init(id: String, name: String, email: String) {
+        self.id = id
+        self.name = name
+        self.email = email
+    }
+}
+
+/// Example of using actors with async/await
+public final class UserService: Sendable {
+    private let manager = UserManager()
+    
+    public init() {}
+    
+    public func fetchUser(id: String) async -> User? {
+        // Actor-isolated access
+        await manager.getUser(for: id)
+    }
+    
+    public func saveUser(_ user: User) async {
+        await manager.setUser(user, for: user.id)
+    }
+}
+```
+
+## Project Structure
+
+```
+project/
+├── Package.swift           # Swift Package Manager manifest
+├── .swiftlint.yml          # SwiftLint configuration
+├── .swift-format           # SwiftFormat configuration
+├── README.md               # Project overview (allowed in root)
+├── CHANGELOG.md            # Version history (allowed in root)
+├── LICENSE                 # Project license (allowed in root)
+├── Sources/
+│   └── YourPackage/
+│       ├── YourPackage.swift
+│       └── ...
+├── Tests/
+│   └── YourPackageTests/
+│       └── YourPackageTests.swift
+└── docs/                   # Project documentation
+```
+
+## Error Handling
+
+- Use Swift's native error handling
+- Create custom error types conforming to `Error`
+- Use `Result` type for functions that don't throw
+- Implement `LocalizedError` for user-facing errors
+
+Example:
+
+```swift
+public enum NetworkError: Error {
+    case invalidURL
+    case noData
+    case decodingFailed(Error)
+    case httpError(statusCode: Int)
+}
+
+extension NetworkError: LocalizedError {
+    public var errorDescription: String? {
+        switch self {
+        case .invalidURL:
+            return "The URL provided was invalid."
+        case .noData:
+            return "No data was received from the server."
+        case .decodingFailed(let error):
+            return "Failed to decode response: \(error.localizedDescription)"
+        case .httpError(let statusCode):
+            return "HTTP error occurred with status code: \(statusCode)"
+        }
+    }
+}
+```
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows for:
+
+1. **Testing** (`swift-test.yml`):
+   - Test on macos-latest
+   - Test on Swift 5.10
+   - Run on iOS, macOS platforms
+
+2. **Linting** (`swift-lint.yml`):
+   - SwiftLint: `swiftlint`
+   - SwiftFormat: `swift-format lint --recursive .`
+   - Build with warnings as errors
+
+## Package Publication
+
+### Publishing Swift Packages
+
+Swift packages are published via Git tags and automatically indexed by Swift Package Index.
+
+**Prerequisites:**
+1. Public Git repository
+2. Valid Package.swift
+3. Semantic version tags
+
+**Publishing Workflow:**
+
+1. Update version documentation
+2. Update CHANGELOG.md
+3. Run quality checks:
+   ```bash
+   swift-format --in-place --recursive Sources Tests
+   swiftlint
+   swift build -Xswiftc -warnings-as-errors
+   swift test
+   ```
+
+4. Create git tag: `git tag 1.0.0 && git push --tags`
+5. Add to Swift Package Index: https://swiftpackageindex.com/add-a-package
+6. Package available via Swift Package Manager
+
+**Publishing Checklist:**
+
+- ✅ All tests passing
+- ✅ SwiftLint passes
+- ✅ Code formatted with swift-format
+- ✅ Build succeeds with warnings as errors
+- ✅ CHANGELOG.md updated
+- ✅ README.md with installation instructions
+- ✅ LICENSE file present
+- ✅ Documentation generated with DocC
+- ✅ Package.swift metadata complete
+- ✅ Semantic version tag created
+
+**Package.swift Metadata:**
+
+```swift
+let package = Package(
+    name: "YourPackage",
+    platforms: [.iOS(.v17), .macOS(.v14)],
+    products: [
+        .library(name: "YourPackage", targets: ["YourPackage"]),
+    ],
+    targets: [
+        .target(name: "YourPackage"),
+        .testTarget(name: "YourPackageTests", dependencies: ["YourPackage"]),
+    ]
+)
+```
+
+**Usage by Consumers:**
+
+```swift
+dependencies: [
+    .package(url: "https://github.com/your-org/your-package.git", from: "1.0.0")
+]
+```
+
+<!-- SWIFT:END -->
+