@sun-asterisk/sunlint 1.3.47 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/swift/C013-no-dead-code.md

@@ -0,0 +1,55 @@
+---
+title: Không để code chết trong codebase
+impact: LOW
+impactDescription: Code không dùng làm tăng kích thước binary, gây nhầm lẫn khi đọc và bảo trì, khiến reviewer tốn thời gian.
+tags: swift, ios, dead-code, cleanup, code-quality
+---
+
+## Không để code chết trong codebase
+
+Code không còn được gọi đến, biến không sử dụng, hàm private không được gọi, hay `#if false` block cần được xóa. Dùng Git history nếu cần khôi phục.
+
+**Incorrect (code chết):**
+
+```swift
+class OrderViewController: UIViewController {
+
+    // Không bao giờ được dùng
+    private func legacyFetchOrders() {
+        // TODO: remove this
+    }
+
+    #if false
+    private func debugHelper() {
+        print("Debug info: \(someVar)")
+    }
+    #endif
+
+    // Biến khai báo nhưng không dùng
+    private let unusedFormatter = DateFormatter()
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        loadOrders()
+    }
+
+    private func loadOrders() { ... }
+}
+```
+
+**Correct (chỉ giữ code đang được dùng):**
+
+```swift
+class OrderViewController: UIViewController {
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+        loadOrders()
+    }
+
+    private func loadOrders() { ... }
+}
+```
+
+**Tools:** SwiftLint (`unused_private_declaration`), Xcode Warnings, SwiftFormat (`unusedPrivateDeclarations`)
+

package/skill-assets/sunlint-code-quality/rules/swift/C014-dependency-injection.md

@@ -0,0 +1,69 @@
+---
+title: Dùng Dependency Injection thay vì khởi tạo trực tiếp
+impact: HIGH
+impactDescription: DI qua protocol giúp dễ dàng mock trong unit test, tách biệt các tầng và tránh coupling cứng giữa các class.
+tags: swift, ios, dependency-injection, testing, architecture, protocol
+---
+
+## Dùng Dependency Injection thay vì khởi tạo trực tiếp
+
+Thay vì khởi tạo dependency trực tiếp bên trong class, hãy inject chúng qua `init` sử dụng protocol. Điều này đặc biệt quan trọng trong iOS khi viết unit test cho ViewModel, Interactor, hay Service.
+
+**Incorrect (khởi tạo trực tiếp):**
+
+```swift
+class OrderViewModel {
+    // Coupling cứng - không thể mock khi test
+    private let apiService = OrderAPIService()
+    private let database = CoreDataManager()
+    private let analytics = FirebaseAnalytics()
+
+    func loadOrders() {
+        apiService.fetchOrders { [weak self] result in
+            // xử lý
+        }
+    }
+}
+```
+
+**Correct (inject qua protocol):**
+
+```swift
+protocol OrderAPIServiceProtocol {
+    func fetchOrders(completion: @escaping (Result<[Order], Error>) -> Void)
+}
+
+protocol AnalyticsProtocol {
+    func track(event: String)
+}
+
+class OrderViewModel {
+    private let apiService: OrderAPIServiceProtocol
+    private let analytics: AnalyticsProtocol
+
+    init(
+        apiService: OrderAPIServiceProtocol = OrderAPIService(),
+        analytics: AnalyticsProtocol = FirebaseAnalytics()
+    ) {
+        self.apiService = apiService
+        self.analytics = analytics
+    }
+
+    func loadOrders() {
+        apiService.fetchOrders { [weak self] result in
+            // xử lý
+        }
+    }
+}
+
+// Unit test dễ dàng
+class MockOrderAPIService: OrderAPIServiceProtocol {
+    func fetchOrders(completion: @escaping (Result<[Order], Error>) -> Void) {
+        completion(.success([Order(id: "1", total: 100)]))
+    }
+}
+let vm = OrderViewModel(apiService: MockOrderAPIService(), analytics: MockAnalytics())
+```
+
+**Tools:** Code Review, Needle/Swinject (DI Framework)
+

package/skill-assets/sunlint-code-quality/rules/swift/C017-no-constructor-logic.md

@@ -0,0 +1,66 @@
+---
+title: Không đặt logic nghiệp vụ trong init
+impact: MEDIUM
+impactDescription: Logic phức tạp trong init làm khó test, gây side-effect không mong muốn và vi phạm nguyên tắc Single Responsibility.
+tags: swift, ios, init, constructor, architecture, code-quality
+---
+
+## Không đặt logic nghiệp vụ trong init
+
+`init` chỉ nên gán giá trị cho các property. Đừng gọi API, đọc file, khởi động timer, hay thực hiện tính toán phức tạp bên trong `init`. Nếu cần, tách ra thành hàm `configure()` hoặc `setup()` gọi sau khi khởi tạo.
+
+**Incorrect (logic trong init):**
+
+```swift
+class UserProfileViewModel {
+    var user: User?
+    var recentOrders: [Order] = []
+
+    init(userId: String) {
+        // Gọi API trong init - không thể control được
+        let user = UserAPIService.shared.fetchUserSync(userId: userId)
+        self.user = user
+
+        // Logic nghiệp vụ trong init
+        if let user = user, user.isPremium {
+            recentOrders = OrderAPIService.shared.fetchOrdersSync(userId: userId)
+        }
+
+        // Đọc file trong init
+        let config = try? JSONDecoder().decode(Config.self, from: Data(contentsOf: configURL))
+    }
+}
+```
+
+**Correct (init đơn giản + hàm setup riêng):**
+
+```swift
+class UserProfileViewModel {
+    private let userId: String
+    private let apiService: UserAPIServiceProtocol
+
+    var user: User?
+    var recentOrders: [Order] = []
+
+    init(userId: String, apiService: UserAPIServiceProtocol) {
+        self.userId = userId
+        self.apiService = apiService
+        // Không có logic nghiệp vụ ở đây
+    }
+
+    // Gọi sau khi khởi tạo - dễ test, dễ control
+    func loadData() async {
+        do {
+            user = try await apiService.fetchUser(userId: userId)
+            if user?.isPremium == true {
+                recentOrders = try await apiService.fetchOrders(userId: userId)
+            }
+        } catch {
+            // xử lý lỗi
+        }
+    }
+}
+```
+
+**Tools:** Code Review, SwiftLint custom rule
+

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
+