@sun-asterisk/sunlint 1.3.48 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/swift/C018-generic-errors.md

@@ -0,0 +1,64 @@
+---
+title: Không throw lỗi generic - dùng Error enum có ngữ cảnh
+impact: MEDIUM
+impactDescription: Lỗi generic không cung cấp đủ thông tin để debug, xử lý hay hiển thị thông báo phù hợp cho người dùng.
+tags: swift, ios, error-handling, enum, code-quality
+---
+
+## Không throw lỗi generic - dùng Error enum có ngữ cảnh
+
+Không dùng `NSError`, `Error` chung chung hay string message tùy tiện. Thay vào đó, định nghĩa enum conform protocol `Error` với từng case cụ thể, mô tả rõ trường hợp thất bại.
+
+**Incorrect (lỗi generic):**
+
+```swift
+func login(email: String, password: String) throws -> User {
+    guard !email.isEmpty else {
+        throw NSError(domain: "error", code: 400, userInfo: nil) // không có ngữ cảnh
+    }
+    guard isValidEmail(email) else {
+        throw NSError(domain: "Invalid email", code: 0, userInfo: nil)
+    }
+    // ...
+}
+```
+
+**Correct (Error enum mô tả rõ ràng):**
+
+```swift
+enum AuthError: Error, LocalizedError {
+    case emptyCredentials
+    case invalidEmailFormat
+    case incorrectPassword
+    case accountLocked(remainingAttempts: Int)
+    case networkUnavailable
+
+    var errorDescription: String? {
+        switch self {
+        case .emptyCredentials:
+            return "Email và mật khẩu không được để trống."
+        case .invalidEmailFormat:
+            return "Định dạng email không hợp lệ."
+        case .incorrectPassword:
+            return "Mật khẩu không đúng."
+        case .accountLocked(let attempts):
+            return "Tài khoản bị khóa. Còn \(attempts) lần thử."
+        case .networkUnavailable:
+            return "Không có kết nối mạng."
+        }
+    }
+}
+
+func login(email: String, password: String) throws -> User {
+    guard !email.isEmpty, !password.isEmpty else {
+        throw AuthError.emptyCredentials
+    }
+    guard isValidEmail(email) else {
+        throw AuthError.invalidEmailFormat
+    }
+    // ...
+}
+```
+
+**Tools:** Code Review, SwiftLint
+

package/skill-assets/sunlint-code-quality/rules/swift/C019-error-log-level.md

@@ -0,0 +1,64 @@
+---
+title: Không dùng mức log error cho lỗi không nghiêm trọng
+impact: LOW
+impactDescription: Lạm dụng .error hay .fault làm nhiễu hệ thống monitoring, khiến việc triage sự cố thực sự mất nhiều thời gian hơn.
+tags: swift, ios, logging, os-log, error-level, code-quality
+---
+
+## Không dùng mức log error cho lỗi không nghiêm trọng
+
+Khi dùng `os_log` hoặc `Logger` (iOS 14+), hãy chọn mức log phù hợp với mức độ nghiêm trọng. `.error` và `.fault` chỉ nên dùng khi có lỗi thực sự ảnh hưởng đến tính năng. Lỗi mạng có thể retry, không có session, hay validation thất bại nên dùng `.warning` hoặc `.info`.
+
+**Incorrect (lạm dụng .error):**
+
+```swift
+import OSLog
+
+let logger = Logger(subsystem: "com.app.network", category: "API")
+
+func fetchUserProfile(userId: String) async {
+    do {
+        let profile = try await apiService.fetchProfile(userId: userId)
+        logger.error("Fetched profile: \(userId)") // .error cho thành công??
+    } catch URLError.notConnectedToInternet {
+        logger.error("No internet - will retry") // nên là .warning
+    } catch let DecodingError.keyNotFound(key, _) {
+        logger.error("Missing key: \(key)") // có thể là .warning
+    }
+}
+```
+
+**Correct (dùng đúng mức log):**
+
+```swift
+import OSLog
+
+let logger = Logger(subsystem: "com.app.network", category: "API")
+
+func fetchUserProfile(userId: String) async {
+    do {
+        let profile = try await apiService.fetchProfile(userId: userId)
+        logger.info("Fetched profile for userId: \(userId)")
+    } catch URLError.notConnectedToInternet {
+        logger.warning("No internet connection, retry scheduled")
+    } catch let DecodingError.keyNotFound(key, _) {
+        logger.warning("API response missing expected key: \(key.stringValue)")
+    } catch {
+        // Lỗi thực sự không lường trước - dùng .error
+        logger.error("Unexpected failure fetching profile userId=\(userId): \(error.localizedDescription)")
+    }
+}
+```
+
+**Mức log và khi nào dùng:**
+
+| Mức | Khi nào dùng |
+|-----|-------------|
+| `.debug` | Thông tin chi tiết chỉ cần lúc development |
+| `.info` | Sự kiện bình thường trong flow nghiệp vụ |
+| `.warning` | Lỗi có thể recover, retry được |
+| `.error` | Lỗi ảnh hưởng tính năng, cần điều tra |
+| `.fault` | Lỗi nghiêm trọng - bug trong hệ thống |
+
+**Tools:** `os.Logger`, OSLog framework
+

package/skill-assets/sunlint-code-quality/rules/swift/C020-no-unused-imports.md

@@ -0,0 +1,47 @@
+---
+title: Không import module không được sử dụng
+impact: LOW
+impactDescription: Import thừa tăng thời gian compile và tạo nhầm lẫn về dependencies thực sự của file.
+tags: swift, ios, imports, compile-time, code-quality
+---
+
+## Không import module không được sử dụng
+
+Xóa tất cả các `import` mà không có symbol nào trong file đang sử dụng. Xcode và SwiftFormat có thể tự phát hiện import thừa.
+
+**Incorrect (import thừa):**
+
+```swift
+import UIKit
+import Foundation
+import Combine        // Không dùng Combine ở đây
+import CoreLocation  // Không dùng location
+import SwiftUI       // File này là UIKit thuần
+
+class ProfileViewController: UIViewController {
+    private let viewModel: ProfileViewModel
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        viewModel.loadProfile()
+    }
+}
+```
+
+**Correct (chỉ import module đang dùng):**
+
+```swift
+import UIKit
+
+class ProfileViewController: UIViewController {
+    private let viewModel: ProfileViewModel
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        viewModel.loadProfile()
+    }
+}
+```
+
+**Tools:** SwiftFormat (`duplicateImports`), Xcode Warnings, periphery
+

package/skill-assets/sunlint-code-quality/rules/swift/C022-no-unused-variables.md

@@ -0,0 +1,46 @@
+---
+title: Không khai báo biến không dùng
+impact: LOW
+impactDescription: Biến không dùng làm tốn bộ nhớ, gây nhầm lẫn khi đọc code và có thể che giấu lỗi logic.
+tags: swift, ios, unused-variables, warnings, code-quality
+---
+
+## Không khai báo biến không dùng
+
+Hãy xóa tất cả biến được khai báo nhưng chưa bao giờ được dùng đến. Nếu cần bỏ qua giá trị trả về, dùng `_` (wildcard).
+
+**Incorrect (biến không dùng):**
+
+```swift
+func processPayment(_ payment: Payment) {
+    let transactionId = UUID().uuidString  // Không bao giờ dùng transactionId
+
+    let result = paymentGateway.charge(payment)  // result không được kiểm tra
+
+    let formatter = NumberFormatter()  // formatter khai báo nhưng không dùng
+    let amount = payment.amount
+    print("Processing \(amount)")
+}
+```
+
+**Correct (dùng _ cho giá trị bỏ qua):**
+
+```swift
+func processPayment(_ payment: Payment) {
+    let result = paymentGateway.charge(payment)
+    guard result.isSuccess else {
+        logger.error("Payment failed: \(result.errorMessage ?? "unknown")")
+        return
+    }
+
+    let amount = payment.amount
+    let formattedAmount = NumberFormatter.currency.string(from: NSNumber(value: amount)) ?? "\(amount)"
+    logger.info("Processed payment: \(formattedAmount)")
+}
+
+// Khi cần bỏ qua return value một cách có chủ ý:
+_ = someOptionalFunction()
+```
+
+**Tools:** Xcode Warnings (`unused variable`), SwiftLint (`unused_closure_parameter`), SwiftFormat (`unusedArguments`)
+

package/skill-assets/sunlint-code-quality/rules/swift/C023-no-duplicate-names.md

@@ -0,0 +1,55 @@
+---
+title: Không khai báo tên trùng lặp trong cùng scope
+impact: LOW
+impactDescription: Shadowing biến gây nhầm lẫn về giá trị nào đang được dùng, dẫn đến bug khó phát hiện.
+tags: swift, ios, shadowing, naming, code-quality
+---
+
+## Không khai báo tên trùng lặp trong cùng scope
+
+Tránh re-declare một biến với tên giống biến bên ngoài scope (variable shadowing). Trường hợp ngoại lệ hợp lý duy nhất là optional binding (`if let user = user`), nhưng cần hạn chế và sử dụng shorthand `if let user` (Swift 5.7+).
+
+**Incorrect (shadowing gây nhầm lẫn):**
+
+```swift
+class CartViewModel {
+    var items: [CartItem] = []
+
+    func calculateTotal(items: [CartItem]) -> Double {
+        // `items` parameter shadowing `self.items`!
+        return items.reduce(0) { $0 + $1.price }  // items nào đây??
+    }
+
+    func applyDiscount(_ discount: Double) {
+        var discount = discount * 0.01  // re-declare discount - confusing!
+        if discount > 0.5 { discount = 0.5 }
+        totalPrice *= (1 - discount)
+    }
+}
+```
+
+**Correct (tên rõ ràng, không shadow):**
+
+```swift
+class CartViewModel {
+    var items: [CartItem] = []
+
+    func calculateTotal(for cartItems: [CartItem]) -> Double {
+        return cartItems.reduce(0) { $0 + $1.price }
+    }
+
+    func applyDiscount(_ discountValue: Double) {
+        let cappedDiscount = min(discountValue * 0.01, 0.5)
+        totalPrice *= (1 - cappedDiscount)
+    }
+}
+
+// Optional binding: Dùng shorthand Swift 5.7+
+func loadProfile(user: User?) {
+    guard let user else { return }  // OK - shorthand, không shadow
+    displayName.text = user.name
+}
+```
+
+**Tools:** SwiftLint (`shadowed_variable`), Xcode Warnings
+

package/skill-assets/sunlint-code-quality/rules/swift/C024-centralize-constants.md

@@ -0,0 +1,68 @@
+---
+title: Tập trung hằng số vào enum hoặc struct
+impact: MEDIUM
+impactDescription: Magic number, hardcoded string rải rác khắp nơi làm khó bảo trì và dễ gây lỗi khi cần thay đổi giá trị.
+tags: swift, ios, constants, magic-numbers, maintainability, code-quality
+---
+
+## Tập trung hằng số vào enum hoặc struct
+
+Không để magic number, string literal, hay URL hardcoded rải rác trong code. Tập trung vào `enum` (namespace không khởi tạo được) hoặc `struct` với `static let`. Dùng `#imageLiteral` và `Asset` enum (thường được SwiftGen tạo) cho resource.
+
+**Incorrect (magic number/string rải rác):**
+
+```swift
+class PaymentViewController: UIViewController {
+    func setupUI() {
+        view.layer.cornerRadius = 12       // magic number
+        submitButton.layer.cornerRadius = 8  // magic number khác
+    }
+
+    func validateCard(number: String) -> Bool {
+        return number.count == 16           // số thẻ phải đúng 16 số?
+    }
+
+    func buildAPIRequest() -> URLRequest {
+        var request = URLRequest(url: URL(string: "https://api.example.com/v2/payments")!)
+        request.setValue("application/json", forHTTPHeaderField: "Content-Type")
+        request.setValue("Bearer sk_live_abc123", forHTTPHeaderField: "Authorization")
+        request.timeoutInterval = 30
+        return request
+    }
+}
+```
+
+**Correct (hằng số tập trung):**
+
+```swift
+// Constants.swift
+enum Constants {
+    enum UI {
+        static let cardCornerRadius: CGFloat = 12
+        static let buttonCornerRadius: CGFloat = 8
+    }
+    enum Payment {
+        static let creditCardLength = 16
+        static let requestTimeout: TimeInterval = 30
+    }
+    enum API {
+        static let baseURL = "https://api.example.com/v2"
+        static let contentTypeJSON = "application/json"
+    }
+}
+
+// Sử dụng
+class PaymentViewController: UIViewController {
+    func setupUI() {
+        view.layer.cornerRadius = Constants.UI.cardCornerRadius
+        submitButton.layer.cornerRadius = Constants.UI.buttonCornerRadius
+    }
+
+    func validateCard(number: String) -> Bool {
+        return number.count == Constants.Payment.creditCardLength
+    }
+}
+```
+
+**Tools:** SwiftLint (`magic_number`), SwiftGen (tự tạo constant cho assets/colors/strings)
+

package/skill-assets/sunlint-code-quality/rules/swift/C029-catch-log-root-cause.md

@@ -0,0 +1,69 @@
+---
+title: Khối catch phải log nguyên nhân gốc rễ của lỗi
+impact: HIGH
+impactDescription: Bắt lỗi mà không log làm mất hoàn toàn thông tin debug, khiến việc tìm nguyên nhân sự cố trở nên rất khó.
+tags: swift, ios, error-handling, logging, debugging, do-catch
+---
+
+## Khối catch phải log nguyên nhân gốc rễ của lỗi
+
+Mỗi `catch` block phải ghi log đầy đủ thông tin: loại lỗi, ngữ cảnh (userId, orderId...) và stack trace khi cần. Không bao giờ bắt lỗi mà không làm gì (silent fail). Dùng `os.Logger` hoặc logging framework thay cho `print()`.
+
+**Incorrect (bắt lỗi im lặng hoặc thiếu thông tin):**
+
+```swift
+import OSLog
+
+func loadUserData(userId: String) async {
+    do {
+        let user = try await apiService.fetchUser(userId: userId)
+        displayUser(user)
+    } catch {
+        // !! Silent fail - mất hoàn toàn lỗi
+    }
+}
+
+func saveOrder(_ order: Order) {
+    do {
+        try coreDataManager.save(order)
+    } catch {
+        print("Error saving") // Không có context, không có error detail
+    }
+}
+```
+
+**Correct (log đầy đủ context):**
+
+```swift
+import OSLog
+
+private let logger = Logger(subsystem: "com.app.user", category: "DataLoader")
+
+func loadUserData(userId: String) async {
+    do {
+        let user = try await apiService.fetchUser(userId: userId)
+        displayUser(user)
+    } catch let apiError as APIError {
+        // Log lỗi có type + context
+        logger.error("Failed to fetch user. userId=\(userId), error=\(apiError.code): \(apiError.localizedDescription)")
+        showErrorBanner(message: apiError.userMessage)
+    } catch {
+        // Lỗi unexpected - log đầy đủ
+        logger.error("Unexpected error loading user. userId=\(userId), error=\(error)")
+        showErrorBanner(message: "Không thể tải thông tin người dùng.")
+    }
+}
+
+func saveOrder(_ order: Order) {
+    do {
+        try coreDataManager.save(order)
+        logger.info("Order saved successfully. orderId=\(order.id)")
+    } catch {
+        logger.error("Failed to save order. orderId=\(order.id), error=\(error)")
+        showSaveFailedAlert()
+    }
+}
+```
+
+**Tools:** `os.Logger`, SwiftLint custom rule, Code Review
+

package/skill-assets/sunlint-code-quality/rules/swift/C030-custom-error-classes.md

@@ -0,0 +1,77 @@
+---
+title: Dùng custom Error enum thay vì NSError hay Error generic
+impact: MEDIUM
+impactDescription: Custom error type cung cấp type-safe error handling, dễ hiển thị thông báo người dùng và không bị mất context khi propagate qua các tầng.
+tags: swift, ios, error-handling, custom-error, enum, code-quality
+---
+
+## Dùng custom Error enum thay vì NSError hay Error generic
+
+Định nghĩa `enum` conform `Error` (hoặc `LocalizedError`) cho từng domain nghiệp vụ. Điều này đảm bảo các lớp xử lý lỗi tường minh theo từng case và tránh mất thông tin khi lỗi propagate.
+
+**Incorrect (lỗi generic):**
+
+```swift
+enum AppError: Error {
+    case generic          // quá mơ hồ
+    case networkError     // không có detail
+    case unknownError     // không hữu ích
+}
+
+func fetchProduct(id: String) throws -> Product {
+    guard !id.isEmpty else {
+        throw AppError.generic  // caller không biết lỗi gì
+    }
+    // ...
+}
+```
+
+**Correct (custom error với đầy đủ case và message):**
+
+```swift
+// Mỗi domain có error type riêng
+enum ProductError: LocalizedError {
+    case emptyProductId
+    case productNotFound(id: String)
+    case outOfStock(productId: String, available: Int)
+    case priceMismatch(expected: Double, actual: Double)
+    case networkUnavailable
+
+    var errorDescription: String? {
+        switch self {
+        case .emptyProductId:
+            return "ID sản phẩm không được để trống."
+        case .productNotFound(let id):
+            return "Không tìm thấy sản phẩm với ID: \(id)."
+        case .outOfStock(let id, let available):
+            return "Sản phẩm \(id) còn \(available) sản phẩm."
+        case .priceMismatch(let expected, let actual):
+            return "Giá không khớp: dự kiến \(expected), thực tế \(actual)."
+        case .networkUnavailable:
+            return "Không có kết nối mạng. Vui lòng thử lại."
+        }
+    }
+}
+
+func fetchProduct(id: String) throws -> Product {
+    guard !id.isEmpty else {
+        throw ProductError.emptyProductId
+    }
+    guard let product = productRepository.find(by: id) else {
+        throw ProductError.productNotFound(id: id)
+    }
+    return product
+}
+
+// Caller xử lý tường minh
+do {
+    let product = try fetchProduct(id: productId)
+} catch ProductError.outOfStock(let id, let available) {
+    showOutOfStockAlert(productId: id, remaining: available)
+} catch let error as ProductError {
+    showErrorAlert(message: error.localizedDescription)
+}
+```
+
+**Tools:** Swift `Error` / `LocalizedError` protocol, Code Review
+

package/skill-assets/sunlint-code-quality/rules/swift/C033-separate-data-access.md

@@ -0,0 +1,89 @@
+---
+title: Tách biệt logic xử lý và truy cập dữ liệu trong tầng service
+impact: HIGH
+impactDescription: Kết hợp logic nghiệp vụ và data access trong cùng một class làm khó test, khó thay đổi storage layer và vi phạm Single Responsibility.
+tags: swift, ios, architecture, repository-pattern, service, code-quality
+---
+
+## Tách biệt logic xử lý và truy cập dữ liệu trong tầng service
+
+ViewModel/Presenter không nên gọi trực tiếp Core Data, UserDefaults, hay network. Tách thành **Repository** (data access) và **UseCase/Service** (business logic). Điều này tuân theo kiến trúc Clean Architecture được Apple khuyến nghị.
+
+**Incorrect (trộn lẫn nghiệp vụ và data access):**
+
+```swift
+class OrderViewModel {
+    func placeOrder(items: [CartItem], userId: String) {
+        // Gọi API trực tiếp trong ViewModel
+        let request = URLRequest(url: URL(string: "https://api.example.com/orders")!)
+        URLSession.shared.dataTask(with: request) { data, _, error in
+            // Xử lý JSON thủ công trong ViewModel
+            guard let data = data,
+                  let order = try? JSONDecoder().decode(Order.self, from: data) else { return }
+
+            // Lưu Core Data trực tiếp trong ViewModel
+            let context = (UIApplication.shared.delegate as! AppDelegate).persistentContainer.viewContext
+            let entity = OrderEntity(context: context)
+            entity.id = order.id
+            try? context.save()
+        }.resume()
+    }
+}
+```
+
+**Correct (Repository + UseCase tách biệt):**
+
+```swift
+// Repository: chỉ lo data access
+protocol OrderRepositoryProtocol {
+    func createOrder(request: CreateOrderRequest) async throws -> Order
+    func saveOrderLocally(_ order: Order) throws
+}
+
+class OrderRepository: OrderRepositoryProtocol {
+    private let apiClient: APIClientProtocol
+    private let coreDataManager: CoreDataManagerProtocol
+
+    init(apiClient: APIClientProtocol, coreDataManager: CoreDataManagerProtocol) {
+        self.apiClient = apiClient
+        self.coreDataManager = coreDataManager
+    }
+
+    func createOrder(request: CreateOrderRequest) async throws -> Order {
+        return try await apiClient.post("/orders", body: request)
+    }
+
+    func saveOrderLocally(_ order: Order) throws {
+        try coreDataManager.insert(order, entityType: OrderEntity.self)
+    }
+}
+
+// UseCase: chỉ lo nghiệp vụ
+class PlaceOrderUseCase {
+    private let orderRepository: OrderRepositoryProtocol
+    private let inventoryService: InventoryServiceProtocol
+
+    func execute(items: [CartItem], userId: String) async throws -> Order {
+        // Kiểm tra tồn kho
+        try await inventoryService.validateAvailability(items: items)
+        let request = CreateOrderRequest(items: items, userId: userId)
+        let order = try await orderRepository.createOrder(request: request)
+        try orderRepository.saveOrderLocally(order)
+        return order
+    }
+}
+
+// ViewModel: chỉ gọi UseCase
+class OrderViewModel {
+    private let placeOrderUseCase: PlaceOrderUseCase
+
+    func placeOrder(items: [CartItem]) async {
+        do {
+            order = try await placeOrderUseCase.execute(items: items, userId: currentUserId)
+        } catch { /* handle */ }
+    }
+}
+```
+
+**Tools:** Code Review, Unit Tests (mock repository dễ dàng)
+

package/skill-assets/sunlint-code-quality/rules/swift/C035-error-context-logging.md

@@ -0,0 +1,66 @@
+---
+title: Log đầy đủ context khi xử lý lỗi
+impact: HIGH
+impactDescription: Thiếu context trong log làm mất khả năng correlate sự kiện, không tái hiện được lỗi production và tăng MTTR (Mean Time To Resolve).
+tags: swift, ios, logging, error-handling, debugging, observability
+---
+
+## Log đầy đủ context khi xử lý lỗi
+
+Khi log lỗi, phải bao gồm: định danh entity (userId, orderId), action đang thực hiện, loại lỗi cụ thể. Dùng `os.Logger` với privacy annotation để tránh log PII ra console.
+
+**Incorrect (log thiếu context):**
+
+```swift
+private let logger = Logger()
+
+func processPayment(_ payment: Payment) async {
+    do {
+        try await paymentService.charge(payment)
+    } catch {
+        logger.error("Payment failed")  // !! Không biết payment nào, tại sao?
+    }
+}
+
+func syncUserData() async {
+    do {
+        try await syncService.fullSync()
+    } catch {
+        print("Sync error: \(error)")  // print thay vì logger, không có user context
+    }
+}
+```
+
+**Correct (log đầy đủ context với privacy):**
+
+```swift
+import OSLog
+
+private let logger = Logger(subsystem: "com.app.payment", category: "Processing")
+
+func processPayment(_ payment: Payment) async {
+    do {
+        try await paymentService.charge(payment)
+        logger.info("Payment succeeded. paymentId=\(payment.id, privacy: .public), amount=\(payment.amount)")
+    } catch PaymentError.insufficientFunds {
+        // Lỗi business - warning
+        logger.warning("Insufficient funds. paymentId=\(payment.id, privacy: .public), userId=\(payment.userId, privacy: .private)")
+    } catch PaymentError.cardDeclined(let code) {
+        logger.error("Card declined. paymentId=\(payment.id, privacy: .public), declineCode=\(code, privacy: .public)")
+    } catch {
+        // Lỗi không ngờ - error level với full context
+        logger.error("Unexpected payment failure. paymentId=\(payment.id, privacy: .public), error=\(error.localizedDescription, privacy: .public)")
+    }
+}
+```
+
+**Privacy annotation cho os.Logger:**
+
+| Annotation | Khi nào dùng |
+|-----------|-------------|
+| `.public` | ID kỹ thuật, error code (an toàn để log) |
+| `.private` | Email, tên, phone (ẩn trong log, chỉ hiện khi debug) |
+| `.sensitive` | Token, mật khẩu (luôn ẩn) |
+
+**Tools:** `os.Logger` với Privacy API, Code Review
+