@sun-asterisk/sunlint 1.3.48 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR006-find-each-batches.md

@@ -0,0 +1,53 @@
+---
+title: "RR006 – Use find_each / in_batches for Bulk Iteration"
+impact: high
+impactDescription: "find_each limits memory to batch size (1000 rows) instead of loading all records at once, preventing OOM in background jobs and rake tasks."
+tags: [ruby, rails, performance, database]
+---
+
+# RR006 – Use find_each / in_batches for Bulk Iteration
+
+## Rule
+
+When iterating over all records (in jobs, scripts, migrations, Rake tasks), always use `find_each` or `in_batches` instead of `all.each` or `where(...).each`.
+
+## Why
+
+`Model.all.each` fetches all matching rows in one SQL query and holds them all in memory. For large tables this causes OOM. `find_each` internally runs batched queries (`LIMIT 1000 ORDER BY id`) and yields one record at a time.
+
+## Wrong
+
+```ruby
+# Loads every user into memory at once
+User.all.each do |user|
+  UserMailer.renewal(user).deliver_later
+end
+
+# Same problem with a where scope
+Order.where(status: 'pending').each { |o| processOrder(o) }
+```
+
+## Correct
+
+```ruby
+# find_each: yields one record at a time, batched under the hood
+User.find_each(batch_size: 500) do |user|
+  UserMailer.renewal(user).deliver_later
+end
+
+# in_batches: yields an ActiveRecord::Relation per batch (useful for bulk updates)
+Order.where(status: 'pending').in_batches(of: 200) do |batch|
+  batch.update_all(processed: true)
+end
+
+# start: / finish: let you resume from a checkpoint
+User.find_each(start: last_processed_id) do |user|
+  # ...
+end
+```
+
+## Notes
+
+- `find_each` requires a primary key — does not work with `select` that omits the PK.
+- Avoid adding an `ORDER BY` other than PK with `find_each`; use `in_batches` if you need custom ordering.
+- For read-only iteration on PostgreSQL, consider `cursor()` from the `activerecord-cursor-pagination` gem for server-side cursors.

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR007-http-status-codes.md

@@ -0,0 +1,76 @@
+---
+title: "RR007 – Return Correct HTTP Status Codes"
+impact: medium
+impactDescription: "Returning 200 OK for errors silently breaks API clients, prevents correct retry logic, and hides failures in monitoring."
+tags: [ruby, rails, api, http]
+---
+
+# RR007 – Return Correct HTTP Status Codes
+
+## Rule
+
+Always pass an explicit `status:` argument to `render json:`. Never return HTTP 200 for validation errors, authorization failures, or not-found resources.
+
+## Wrong
+
+```ruby
+def create
+  @user = User.new(user_params)
+  if @user.save
+    render json: @user                # ❌ no status — defaults to 200
+  else
+    render json: { errors: @user.errors }   # ❌ 200 on failure
+  end
+end
+
+def show
+  @user = User.find_by(id: params[:id])
+  render json: @user   # ❌ returns 200 with null body if not found
+end
+```
+
+## Correct
+
+```ruby
+def create
+  @user = User.new(user_params)
+  if @user.save
+    render json: UserResource.new(@user), status: :created          # 201
+  else
+    render json: { errors: @user.errors.full_messages }, status: :unprocessable_entity  # 422
+  end
+end
+
+def show
+  @user = User.find(params[:id])    # raises ActiveRecord::RecordNotFound → rescued to 404
+  render json: UserResource.new(@user), status: :ok
+end
+
+# In ApplicationController
+rescue_from ActiveRecord::RecordNotFound, with: :not_found
+rescue_from Pundit::NotAuthorizedError,   with: :forbidden
+
+def not_found
+  render json: { error: 'Not found' }, status: :not_found           # 404
+end
+def forbidden
+  render json: { error: 'Forbidden' }, status: :forbidden           # 403
+end
+```
+
+## Status code reference
+
+| Scenario | Status |
+|---|---|
+| Create success | `201 :created` |
+| Update/delete success | `200 :ok` |
+| No content | `204 :no_content` |
+| Validation failed | `422 :unprocessable_entity` |
+| Not found | `404 :not_found` |
+| Unauthorized (not logged in) | `401 :unauthorized` |
+| Forbidden (not allowed) | `403 :forbidden` |
+
+## Notes
+
+- Use symbol form (`:created`) — it's self-documenting and immune to numeric typos.
+- Centralize rescue_from in `ApplicationController` or a concern rather than per-action `rescue`.

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR008-before-action-auth.md

@@ -0,0 +1,77 @@
+---
+title: "RR008 – Enforce Authentication with before_action"
+impact: high
+impactDescription: "Missing before_action :authenticate_user! leaves actions publicly accessible by default — opt-out is safer than opt-in."
+tags: [ruby, rails, security, authentication]
+---
+
+# RR008 – Enforce Authentication with before_action
+
+## Rule
+
+Place `before_action :authenticate_user!` in `ApplicationController`. Use `skip_before_action` only for explicitly public endpoints. Never rely on per-action checks or assume private routes are protected.
+
+## Why
+
+If authentication is applied per-action (opt-in), a new action will be public by default — a common source of auth bypass vulnerabilities. Opt-out (skip for public endpoints) is the safe default.
+
+## Wrong
+
+```ruby
+# Opt-in per controller — new actions are public by default
+class PostsController < ApplicationController
+  def index
+    authenticate_user!   # ❌ developer must remember to call this
+    @posts = Post.all
+  end
+
+  def create
+    # ❌ forgot authenticate_user! — publicly writable
+    Post.create!(post_params)
+  end
+end
+
+# ApplicationController with no global hook
+class ApplicationController < ActionController::API
+  # nothing — every action is public until protected
+end
+```
+
+## Correct
+
+```ruby
+# ApplicationController — everything requires auth
+class ApplicationController < ActionController::API
+  include Devise::Controllers::Helpers   # or your auth layer
+  before_action :authenticate_user!
+
+  private
+
+  def current_user_id
+    current_user.id
+  end
+end
+
+# Public endpoints explicitly opt out
+class SessionsController < ApplicationController
+  skip_before_action :authenticate_user!, only: [:create, :destroy]
+  
+  def create
+    # login — intentionally public
+  end
+end
+
+class HealthController < ApplicationController
+  skip_before_action :authenticate_user!
+  
+  def show
+    render json: { status: 'ok' }
+  end
+end
+```
+
+## Notes
+
+- For Devise APIs, use `authenticate_user!` from `Devise::Controllers::Helpers` or the Devise-JWT extension.
+- Documenting `skip_before_action` with a comment explaining WHY the action is public improves auditability.
+- Add an integration test that requests every route without auth and asserts `status: 401` for protected ones.

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR009-rails-credentials.md

@@ -0,0 +1,61 @@
+---
+title: "RR009 – Store Secrets in Rails Credentials, Not in Code"
+impact: high
+impactDescription: "Hardcoded secrets in source code are committed to Git history and exposed permanently even after deletion."
+tags: [ruby, rails, security, secrets]
+---
+
+# RR009 – Store Secrets in Rails Credentials
+
+## Rule
+
+All secret values (API keys, tokens, signing secrets, passwords) must live in `config/credentials.yml.enc` or environment variables. Never hardcode them in source files, `config/initializers/`, or `database.yml`.
+
+## Why
+
+Once a secret is committed, it lives in Git history forever. Rotating it requires a force-push and re-access revocation. Rails credentials are encrypted at rest; the master key (`config/master.key` or `RAILS_MASTER_KEY`) is the only secret that must stay outside source control.
+
+## Wrong
+
+```ruby
+# config/initializers/stripe.rb
+Stripe.api_key = 'sk_live_XXXXXXXXXXXXX'    # ❌ hardcoded
+
+# config/database.yml
+production:
+  password: 'my_db_password_123'            # ❌ hardcoded
+
+# app/services/sendgrid_service.rb
+API_KEY = 'SG.xxxxxxxxxxxx'                 # ❌ constant with embedded secret
+```
+
+## Correct
+
+```bash
+# Add / edit secrets (encrypts automatically)
+bin/rails credentials:edit --environment production
+
+# config/credentials/production.yml.enc (decrypted view)
+stripe:
+  api_key: sk_live_XXXXXXXXXXXXX
+sendgrid:
+  api_key: SG.xxxxxxxxxxxx
+```
+
+```ruby
+# Access anywhere in application code
+Stripe.api_key = Rails.application.credentials.stripe[:api_key]
+
+# Or via environment variable (suitable for container deployments)
+Stripe.api_key = ENV.fetch('STRIPE_API_KEY')
+
+# config/database.yml (env var form)
+production:
+  password: <%= ENV['DATABASE_PASSWORD'] %>
+```
+
+## Notes
+
+- `config/master.key` and `config/credentials/production.key` must be in `.gitignore` and never committed.
+- In CI/CD, inject `RAILS_MASTER_KEY` as a masked environment variable, not in cleartext config.
+- For team environments with multiple people needing access, prefer environment variables or a vault (e.g., HashiCorp Vault, AWS Secrets Manager) over shared credentials files.

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR010-scopes.md

@@ -0,0 +1,57 @@
+---
+title: "RR010 – Define Reusable Query Scopes in Models"
+impact: medium
+impactDescription: "Inline where() chains scattered across controllers make conditions hard to reuse, test, and change in one place."
+tags: [ruby, rails, code-quality, database]
+---
+
+# RR010 – Define Reusable Query Scopes in Models
+
+## Rule
+
+Encapsulate frequently used `where`, `order`, and `joins` conditions as named scopes on the model. Controllers call scopes by name — they do not build query logic inline.
+
+## Why
+
+Query conditions duplicated across controllers and services violate DRY and make maintenance hazardous. A scope is a named, composable, chainable query fragment that belongs to the model (the owner of the data).
+
+## Wrong
+
+```ruby
+# Controller 1
+@posts = Post.where(published: true).where('created_at > ?', 30.days.ago).order(created_at: :desc)
+
+# Controller 2 (duplicate, slightly different)
+@featured = Post.where(published: true).where(featured: true).order(created_at: :desc)
+
+# Controller 3 (wrong date, bug introduced by copy-paste)
+@recent = Post.where(published: true).where('created_at > ?', 7.days.ago).order(created_at: :asc)
+```
+
+## Correct
+
+```ruby
+# app/models/post.rb
+class Post < ApplicationRecord
+  scope :published,  -> { where(published: true) }
+  scope :featured,   -> { where(featured: true) }
+  scope :recent,     -> { where('created_at > ?', 30.days.ago) }
+  scope :by_newest,  -> { order(created_at: :desc) }
+
+  # Scopes with parameters
+  scope :created_after, ->(date) { where('created_at > ?', date) }
+  scope :by_author,     ->(author_id) { where(author_id: author_id) }
+end
+
+# Controllers compose scopes — clean, readable, no SQL inline
+@posts    = Post.published.recent.by_newest
+@featured = Post.published.featured.by_newest
+@mine     = Post.published.by_author(current_user.id).recent
+```
+
+## Notes
+
+- Scopes return `ActiveRecord::Relation` — they are chainable by design.
+- Scopes should be tested independently in model specs: `Post.published` should only return published posts.
+- For complex multi-table logic, consider a Query Object (like a service object) that wraps the relation.
+- Avoid scopes with side effects (no writes, callbacks, or network calls).

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR011-counter-cache.md

@@ -0,0 +1,59 @@
+---
+title: "RR011 – Use counter_cache to Avoid Count N+1"
+impact: medium
+impactDescription: "post.comments.count in a collection loop fires one COUNT query per row; counter_cache collapses this to zero extra queries."
+tags: [ruby, rails, performance, database]
+---
+
+# RR011 – Use counter_cache to Avoid Count N+1
+
+## Rule
+
+When displaying association counts in collection views or API responses (comment counts, like counts, etc.), use `counter_cache: true` on the `belongs_to` side instead of computing `association.count` in-loop.
+
+## Why
+
+`post.comments.count` (or `.size` when collection is not loaded) executes a `COUNT(*)` SQL query. In a list of 50 posts this fires 50 extra queries. `counter_cache` maintains a denormalized `comments_count` column on the parent table updated atomically by Rails on create/destroy.
+
+## Wrong
+
+```ruby
+# In API serializer or view — fires N COUNT queries
+posts.each do |post|
+  count = post.comments.count    # ❌ 1 COUNT query per post
+end
+
+# JSON response that triggers N+1
+render json: @posts.map { |p| { id: p.id, comment_count: p.comments.count } }
+```
+
+## Correct
+
+```ruby
+# Migration: add the cache column
+add_column :posts, :comments_count, :integer, default: 0, null: false
+# Backfill: Post.find_each { |p| Post.reset_counters(p.id, :comments) }
+
+# Model association
+class Comment < ApplicationRecord
+  belongs_to :post, counter_cache: true
+  # Rails now auto-increments/decrements posts.comments_count
+end
+
+class Post < ApplicationRecord
+  has_many :comments
+end
+
+# Usage — no extra query
+posts.each do |post|
+  count = post.comments_count    # ✅ reads the cached column, zero extra queries
+end
+
+render json: @posts.map { |p| { id: p.id, comment_count: p.comments_count } }
+```
+
+## Notes
+
+- Reset cache after backfills: `Post.find_each { |p| Post.reset_counters(p.id, :comments) }`.
+- If using soft-delete (`acts_as_paranoid`, `discard`), counter_cache won't exclude soft-deleted records — use a custom query in that case.
+- Alternative when migration is not possible: `Post.includes(:comments)` + `post.comments.size` (`.size` uses already-loaded collection, no extra query).

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR012-render-json-status.md

@@ -0,0 +1,42 @@
+---
+title: "RR012 – Always Include status: in render json:"
+impact: medium
+impactDescription: "Omitting status: defaults to 200, masking errors and breaking API client error-handling."
+tags: [ruby, rails, api, http]
+---
+
+# RR012 – Always Include `status:` in `render json:`
+
+## Rule
+
+Every `render json:` call must include an explicit `status:` keyword argument. Do not rely on the implicit `200` default.
+
+## Why
+
+This is a codified subset of RR007 focused on a single easy-to-miss omission. Implicit 200 is the default only because it's the most common case — it doesn't mean it's always correct. Explicit status makes intent clear in code review and prevents errors from silently appearing as successes to API clients.
+
+## Wrong
+
+```ruby
+render json: @user                                # ❌ implicit 200
+render json: { errors: @user.errors.full_messages }   # ❌ looks like success to client
+render json: { message: 'Deleted' }              # ❌ should be 200 or 204 — unclear
+```
+
+## Correct
+
+```ruby
+render json: UserResource.new(@user), status: :ok               # 200
+render json: UserResource.new(@user), status: :created          # 201 for POST
+render json: { errors: @user.errors.full_messages },
+       status: :unprocessable_entity                            # 422
+render json: { message: 'Deleted' }, status: :ok                # 200
+# OR for no-body deletes:
+head :no_content                                                # 204, no body
+```
+
+## Notes
+
+- Use Rails symbol names (`:ok`, `:created`, `:no_content`) — not integers — for readability.
+- `head :no_content` is the cleanest response for DELETE with no return body.
+- Pair this rule with consistent `rescue_from` in ApplicationController so all error paths also have correct status codes (see RR007).

package/skill-assets/sunlint-code-quality/rules/swift/C006-verb-noun-functions.md

@@ -0,0 +1,37 @@
+---
+title: Tên hàm phải là động từ hoặc động từ + danh từ
+impact: MEDIUM
+impactDescription: Tên hàm mô tả đúng hành động giúp code dễ đọc và giảm cognitive load khi review PR.
+tags: swift, ios, naming, readability, code-quality
+---
+
+## Tên hàm phải là động từ hoặc động từ + danh từ
+
+Tên hàm phải bắt đầu bằng động từ hoặc cụm động từ + danh từ, mô tả rõ ràng hành động mà hàm thực hiện. Tránh đặt tên mơ hồ như `data()`, `handle()`, `process()`.
+
+**Incorrect (tên không rõ hành động):**
+
+```swift
+class UserManager {
+    func data() -> User? { ... }           // Không rõ là lấy hay tạo
+    func handle(_ error: Error) { ... }    // handle là gì?
+    func process(_ payment: Payment) { ... } // process không nói lên kết quả
+    func userInfo(for id: String) { ... }  // thiếu động từ
+}
+```
+
+**Correct (tên thể hiện hành động rõ ràng):**
+
+```swift
+class UserManager {
+    func fetchUser(by id: String) -> User? { ... }
+    func logError(_ error: Error) { ... }
+    func submitPayment(_ payment: Payment) throws { ... }
+    func loadUserProfile(userId: String) async throws -> UserProfile { ... }
+    func validateEmail(_ email: String) -> Bool { ... }
+    func clearCache() { ... }
+}
+```
+
+**Tools:** SwiftLint custom rule, Code Review
+

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
+