@sun-asterisk/sunlint 1.3.47 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR003-service-objects.md

@@ -0,0 +1,99 @@
+---
+title: "RR003 – Extract Business Logic into Service Objects"
+impact: high
+impactDescription: "Fat models and fat controllers are untestable, hard to reuse, and prone to circular dependencies. Service objects isolate business logic into a single callable unit."
+tags: [ruby, rails, architecture, service-layer]
+---
+
+# RR003 – Extract Business Logic into Service Objects
+
+## Rule
+
+Business logic that involves more than a single model update, an external API call, or conditional branching belongs in a dedicated service object under `app/services/`, not in models or controllers.
+
+## Why
+
+- Fat models accumulate unrelated behaviour, making them hard to test in isolation.
+- Fat controllers mix HTTP concerns (params, redirects) with domain rules.
+- Service objects are plain Ruby objects (POROs) — no Rails magic needed to test them.
+
+## Wrong
+
+```ruby
+# Fat controller: business logic mixed with HTTP handling
+class OrdersController < ApplicationController
+  def create
+    @order = Order.new(order_params)
+    @order.total = @order.items.sum(&:price) * (1 - current_user.discount)
+    if @order.save
+      Stripe::Charge.create(amount: @order.total_cents, ...)
+      OrderMailer.confirmation(@order).deliver_later
+      redirect_to @order
+    else
+      render :new
+    end
+  end
+end
+
+# Fat model: calling external APIs from ActiveRecord callbacks
+class Order < ApplicationRecord
+  after_create :charge_card
+  def charge_card
+    Stripe::Charge.create(...)
+  end
+end
+```
+
+## Correct
+
+```ruby
+# app/services/place_order_service.rb
+class PlaceOrderService
+  Result = Struct.new(:order, :success?, :error, keyword_init: true)
+
+  def initialize(user:, params:, payment_gateway: Stripe)
+    @user = user
+    @params = params
+    @payment_gateway = payment_gateway
+  end
+
+  def call
+    order = build_order
+    return Result.new(order: order, success?: false, error: order.errors) unless order.save
+
+    charge_payment(order)
+    OrderMailer.confirmation(order).deliver_later
+    Result.new(order: order, success?: true)
+  rescue PaymentError => e
+    order.destroy
+    Result.new(success?: false, error: e.message)
+  end
+
+  private
+
+  def build_order
+    Order.new(**@params, total: calculate_total, user: @user)
+  end
+  # ...
+end
+
+# Controller stays thin
+class OrdersController < ApplicationController
+  def create
+    result = PlaceOrderService.new(user: current_user, params: order_params).call
+    if result.success?
+      redirect_to result.order
+    else
+      @order = result.order
+      render :new
+    end
+  end
+end
+```
+
+## Notes
+
+- Service objects should be callable via `#call` (standard Ruby convention, works with `Proc#call` duck-typing).
+- Return a `Result` struct or use `dry-monads` for explicit success/failure signalling.
+- Place in `app/services/` — Rails autoloads from this directory by default.
+- Keep one public method (`call`) — additional extraction goes into private methods.

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR004-active-job-background.md

@@ -0,0 +1,67 @@
+---
+title: "RR004 – Use ActiveJob for Background Work"
+impact: high
+impactDescription: "Spawning raw threads or doing heavy work inline blocks the Puma thread, causing request timeouts and memory leaks."
+tags: [ruby, rails, performance, background-jobs]
+---
+
+# RR004 – Use ActiveJob for Background Work
+
+## Rule
+
+Any operation that is slow (email, external API, report generation, file processing) or must retry on failure must be enqueued via `ActiveJob`, not executed inline in the request or in a raw `Thread.new`.
+
+## Why
+
+- `Thread.new` in a Rails controller shares the request's database connection until it's reclaimed, causing connection pool exhaustion.
+- Inline work blocks the Puma thread until completion — the user waits.
+- ActiveJob provides retry semantics, dead-letter queues, and observable failure via your queue backend (Sidekiq, GoodJob, Solid Queue).
+
+## Wrong
+
+```ruby
+# Inline — user waits for CSV export to complete
+def export
+  @orders = Order.all
+  csv = generate_csv(@orders)   # could take 10+ seconds
+  send_data csv, filename: 'orders.csv'
+end
+
+# Raw thread — races on connection pool, no retry, no observability
+def send_welcome_email
+  Thread.new { UserMailer.welcome(@user).deliver_now }
+  redirect_to root_path
+end
+```
+
+## Correct
+
+```ruby
+# app/jobs/generate_order_export_job.rb
+class GenerateOrderExportJob < ApplicationJob
+  queue_as :exports
+  retry_on Net::TimeoutError, wait: 5.seconds, attempts: 3
+  discard_on ActiveRecord::RecordNotFound
+
+  def perform(user_id, filters)
+    user = User.find(user_id)
+    csv = OrderExportService.new(filters).generate
+    UserMailer.export_ready(user, csv).deliver_now
+  end
+end
+
+# Controller
+def export
+  GenerateOrderExportJob.perform_later(current_user.id, export_params.to_h)
+  redirect_to orders_path, notice: 'Export will be emailed to you.'
+end
+
+# Mailer — always defer with deliver_later
+UserMailer.welcome(@user).deliver_later
+```
+
+## Notes
+
+- Use `perform_later` (async) in production; `perform_now` only in tests / sync scenarios.
+- Configure the queue backend in `config/application.rb`: `config.active_job.queue_adapter = :sidekiq`.
+- Serialize only primitive-safe arguments (IDs, not AR objects) — AR objects go stale between enqueue and perform.

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR005-pagination.md

@@ -0,0 +1,53 @@
+---
+title: "RR005 – Paginate All Collection Endpoints"
+impact: medium
+impactDescription: "Loading unbounded collections into memory causes OOM crashes and unacceptably slow responses at scale."
+tags: [ruby, rails, performance, pagination]
+---
+
+# RR005 – Paginate All Collection Endpoints
+
+## Rule
+
+Every controller action that returns a list must apply pagination. Never return an unbounded collection with `Model.all` or `.where(...)` without a `.page` or `.limit` call.
+
+## Why
+
+A table that currently has 1,000 rows will have millions. An unguarded `Order.all` will load all records into memory on each request. Pagination (Kaminari or Pagy) is the standard Rails solution.
+
+## Wrong
+
+```ruby
+def index
+  @orders = Order.all                         # ❌ unbounded
+  @users  = User.where(active: true)          # ❌ unbounded
+  render json: @orders
+end
+```
+
+## Correct
+
+```ruby
+# Gemfile: gem 'pagy'  —OR—  gem 'kaminari'
+
+# With Pagy (preferred — fastest)
+include Pagy::Backend
+
+def index
+  @pagy, @orders = pagy(Order.order(created_at: :desc), items: 25)
+  render json: { orders: @orders, meta: pagy_metadata(@pagy) }
+end
+
+# With Kaminari
+def index
+  @orders = Order.order(created_at: :desc).page(params[:page]).per(25)
+  render json: @orders
+end
+```
+
+## Notes
+
+- Default page size should be configurable but capped (e.g., max 100 per page).
+- Pass `params[:per_page]` through an explicit allowlist — never directly into `.per()`.
+- Pagy is significantly faster than Kaminari for large tables; prefer it in new projects.
+- For cursor-based APIs (infinite scroll / mobile), use `pagy_cursor` or write manual `WHERE id > last_id LIMIT n` queries.

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
+