@sun-asterisk/sunlint 1.3.47 → 1.3.49

package/skill-assets/sunlint-code-quality/rules/python/P009-logging-lazy-format.md

@@ -0,0 +1,50 @@
+---
+title: Use Lazy Formatting in Logging Calls
+impact: MEDIUM
+impactDescription: Eager string interpolation in logging (f-strings or %) evaluates and allocates the string even when the log level is disabled, wasting CPU and memory in production.
+tags: python, logging, performance, quality
+---
+
+## Use Lazy Formatting in Logging Calls
+
+Python's `logging` module accepts a format string and arguments **separately**. The string interpolation only happens if the message will actually be emitted (i.e., the log level is enabled). Using f-strings or `%` interpolation beforehand evaluates the string unconditionally, even if `DEBUG` is disabled.
+
+**Incorrect:**
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+user_id = get_user_id()
+payload = serialize(data)
+
+# These always evaluate the f-string / % formatting, even if DEBUG is off
+logger.debug(f"Processing user {user_id} with payload {payload}")
+logger.info("Request from %s: %s" % (ip_address, request.path))
+logger.warning("Slow query: " + str(query_time) + "ms")
+```
+
+**Correct:**
+```python
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Formatting deferred — only if DEBUG is enabled
+logger.debug("Processing user %s with payload %s", user_id, payload)
+logger.info("Request from %s: %s", ip_address, request.path)
+logger.warning("Slow query: %sms", query_time)
+
+# For complex objects, use lazy repr via %r
+logger.debug("Event received: %r", event)
+
+# Exception info — use exc_info=True or logger.exception()
+try:
+    call_external_api()
+except requests.RequestException as e:
+    logger.error("External API failed for user %s: %s", user_id, e, exc_info=True)
+    # or equivalently inside an except block:
+    # logger.exception("External API failed for user %s", user_id)
+```
+
+**Tools:** Ruff `G004` (logging-f-string), `W1201` in Pylint (logging-not-lazy), `W1202` (logging-format-interpolation), `TRY400` (error-instead-of-exception), flake8-logging-format

package/skill-assets/sunlint-code-quality/rules/python/P010-exception-chaining.md

@@ -0,0 +1,57 @@
+---
+title: Use raise...from to Chain Exceptions
+impact: MEDIUM
+impactDescription: Rethrowing an exception without raise...from loses the original traceback, making it impossible to diagnose the root cause in production logs.
+tags: python, exceptions, error-handling, traceability, quality
+---
+
+## Use raise...from to Chain Exceptions
+
+When catching an exception and raising a different (or more specific) one, use `raise NewException("msg") from original_exception` to preserve the full causal chain. Without `from`, Python 3 still shows an implicit chain, but the context can be confusing. Using `from` makes the chain explicit and intentional.
+
+Using `raise ... from None` deliberately suppresses the original context when it adds no value to the end user.
+
+**Incorrect:**
+```python
+import json
+
+def load_config(path: str) -> dict:
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except json.JSONDecodeError:
+        raise ValueError("Config file is malformed")  # original traceback lost
+
+def get_user(user_id: int) -> dict:
+    try:
+        return db.find_by_id(user_id)
+    except DatabaseError:
+        raise RuntimeError("Failed to fetch user")  # loses DB error context
+```
+
+**Correct:**
+```python
+import json
+
+def load_config(path: str) -> dict:
+    try:
+        with open(path, encoding="utf-8") as f:
+            return json.load(f)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Config file '{path}' is malformed") from e  # chain preserved
+
+def get_user(user_id: int) -> dict:
+    try:
+        return db.find_by_id(user_id)
+    except DatabaseError as e:
+        raise UserNotFoundError(f"User {user_id} could not be fetched") from e
+
+# Suppress context intentionally (e.g., to hide internal DB details from callers)
+def validate_token(token: str) -> None:
+    try:
+        jwt.decode(token, SECRET)
+    except jwt.ExpiredSignatureError:
+        raise AuthenticationError("Token has expired") from None
+```
+
+**Tools:** Ruff `W0707` / `raise-missing-from`, `TRY200` (reraise-no-cause), `B904` (raise-without-from-inside-except), Pylint `W0707`, flake8-bugbear

package/skill-assets/sunlint-code-quality/rules/python/P011-subprocess-check.md

@@ -0,0 +1,59 @@
+---
+title: Pass Explicit check= to subprocess.run
+impact: HIGH
+impactDescription: subprocess.run silently ignores non-zero exit codes by default; a failed command goes undetected and subsequent code runs on corrupt or missing output.
+tags: python, subprocess, error-handling, quality, security
+---
+
+## Pass Explicit check= to subprocess.run
+
+`subprocess.run()` has `check=False` by default, meaning a command that exits with a non-zero status (indicating failure) does not raise an exception. Code that follows assumes success and may operate on missing or corrupt output without any error ever being raised.
+
+Always pass `check=True` unless you explicitly intend to handle failures yourself by inspecting `returncode`.
+
+**Incorrect:**
+```python
+import subprocess
+
+# Exit code ignored — if ffmpeg fails, output file doesn't exist
+subprocess.run(["ffmpeg", "-i", "input.mp4", "output.mp4"])
+
+# result.returncode is never checked
+result = subprocess.run(["git", "pull"])
+print("Done")  # runs even if git pull failed
+
+# capture_output=True but still no check
+result = subprocess.run(
+    ["python", "migrate.py"],
+    capture_output=True,
+    text=True,
+)
+apply_migrations()  # runs even if migrate.py failed
+```
+
+**Correct:**
+```python
+import subprocess
+
+# Raises CalledProcessError if command fails
+subprocess.run(
+    ["ffmpeg", "-i", "input.mp4", "output.mp4"],
+    check=True,
+)
+
+# Or capture output and check explicitly
+result = subprocess.run(
+    ["python", "migrate.py"],
+    capture_output=True,
+    text=True,
+    check=True,                  # raises on non-zero exit code
+)
+apply_migrations()  # only reached if migration succeeded
+
+# When you WANT to handle failures yourself — explicit intent:
+result = subprocess.run(["git", "pull"], check=False)
+if result.returncode != 0:
+    logger.warning("git pull failed with code %d", result.returncode)
+```
+
+**Tools:** Ruff `PLW1510` (subprocess-run-without-check), Pylint `W1510`, Bandit `S603`, flake8-bugbear

package/skill-assets/sunlint-code-quality/rules/python/P012-requests-timeout.md

@@ -0,0 +1,70 @@
+---
+title: Always Set timeout for HTTP Requests
+impact: HIGH
+impactDescription: HTTP requests without a timeout can hang indefinitely, exhausting thread pools and connection pools, causing cascading failures and outages in production services.
+tags: python, requests, http, reliability, quality
+---
+
+## Always Set timeout for HTTP Requests
+
+The `requests` library and similar HTTP clients have **no default timeout**. A single slow or unresponsive server can cause a thread to block indefinitely, exhausting thread pools and causing the entire service to become unresponsive. Always set an explicit `timeout` on every outbound HTTP call.
+
+**Incorrect:**
+```python
+import requests
+
+# Hangs forever if server is unresponsive
+response = requests.get("https://api.example.com/data")
+
+# Also no timeout
+session = requests.Session()
+response = session.post(
+    "https://api.example.com/webhook",
+    json=payload,
+)
+
+# httpx — same risk
+import httpx
+response = httpx.get("https://api.example.com/items")
+```
+
+**Correct:**
+```python
+import requests
+
+# Set both connect and read timeouts as a tuple
+response = requests.get(
+    "https://api.example.com/data",
+    timeout=(3.05, 27),   # (connect_timeout, read_timeout) in seconds
+)
+
+# Or a single value for both
+response = requests.post(
+    "https://api.example.com/webhook",
+    json=payload,
+    timeout=10,           # applies to both connect and read
+)
+response.raise_for_status()
+
+# httpx — also requires explicit timeout
+import httpx
+
+with httpx.Client(timeout=httpx.Timeout(connect=3.0, read=30.0)) as client:
+    response = client.get("https://api.example.com/items")
+```
+
+**Configure timeouts at the session level:**
+```python
+# Apply uniformly to all requests from the session
+session = requests.Session()
+adapter = requests.adapters.HTTPAdapter(max_retries=3)
+session.mount("https://", adapter)
+
+DEFAULT_TIMEOUT = (3.05, 27)
+
+def get_with_timeout(url: str, **kwargs) -> requests.Response:
+    kwargs.setdefault("timeout", DEFAULT_TIMEOUT)
+    return session.get(url, **kwargs)
+```
+
+**Tools:** Ruff `W3101` (missing-timeout), Pylint `W3101`, Bandit `S113`, flake8

package/skill-assets/sunlint-code-quality/rules/python/P013-no-global-statement.md

@@ -0,0 +1,73 @@
+---
+title: Avoid global Statement in Functions
+impact: MEDIUM
+impactDescription: The global statement creates hidden dependencies between functions and module-level state, making code order-dependent, untestable, and unsafe for concurrent use.
+tags: python, global, state, quality, concurrency
+---
+
+## Avoid global Statement in Functions
+
+Using `global var` inside a function creates an implicit dependency on module-level mutable state. The function's behavior changes depending on which other functions have already run, making it nearly impossible to test in isolation. In multi-threaded or async contexts, it introduces race conditions.
+
+Pass state explicitly through parameters and return values, or encapsulate it in a class.
+
+**Incorrect:**
+```python
+counter = 0
+last_user = None
+
+def process_request(user_id: int) -> None:
+    global counter, last_user   # hidden mutation of module state
+    counter += 1
+    last_user = user_id
+    do_work(user_id)
+
+def get_stats() -> dict:
+    return {"total": counter, "last": last_user}
+
+# Tests are order-dependent and cannot run in parallel
+def test_process_request():
+    process_request(42)
+    assert counter == 1   # depends on no other test having run first
+```
+
+**Correct:**
+```python
+from dataclasses import dataclass, field
+from threading import Lock
+
+@dataclass
+class RequestTracker:
+    _count: int = 0
+    _last_user: int | None = None
+    _lock: Lock = field(default_factory=Lock, compare=False)
+
+    def record(self, user_id: int) -> None:
+        with self._lock:
+            self._count += 1
+            self._last_user = user_id
+
+    def stats(self) -> dict:
+        return {"total": self._count, "last": self._last_user}
+
+tracker = RequestTracker()
+
+def process_request(user_id: int, tracker: RequestTracker) -> None:
+    tracker.record(user_id)
+    do_work(user_id)
+
+# Tests are isolated
+def test_process_request():
+    t = RequestTracker()
+    process_request(42, t)
+    assert t.stats()["total"] == 1
+```
+
+**Acceptable module-level constants (no `global` needed):**
+```python
+# Constants never mutated — global statement not needed or used
+MAX_RETRIES = 3
+DEFAULT_TIMEOUT = 30.0
+```
+
+**Tools:** Ruff `PLW0603` (global-statement), Pylint `W0603`, SonarQube Python `S1854`, flake8

package/skill-assets/sunlint-code-quality/rules/python/P014-no-modify-collection-while-iterating.md

@@ -0,0 +1,66 @@
+---
+title: Do Not Modify Collection While Iterating Over It
+impact: HIGH
+impactDescription: Adding or removing items from a list, dict, or set while iterating over it causes RuntimeError, skipped elements, or undefined behavior depending on the collection type.
+tags: python, iteration, bugs, pitfalls, quality
+---
+
+## Do Not Modify Collection While Iterating Over It
+
+Modifying a `dict` or `set` while iterating raises `RuntimeError: dictionary changed size during iteration` / `set changed size during iteration`. Modifying a `list` during iteration does **not** raise an error but silently skips or processes elements multiple times, producing wrong results.
+
+Always iterate over a copy, build a new collection, or collect modifications and apply them after the loop.
+
+**Incorrect:**
+```python
+# dict — raises RuntimeError
+config = {"debug": True, "deprecatedKey": "val", "timeout": 30}
+
+for key in config:
+    if key.startswith("deprecated"):
+        del config[key]   # RuntimeError: dictionary changed size during iteration
+
+# set — raises RuntimeError
+seen = {1, 2, 3, 4, 5}
+
+for item in seen:
+    if item % 2 == 0:
+        seen.discard(item)   # RuntimeError: set changed size during iteration
+
+# list — silent bug: skips elements
+items = [1, 2, 2, 3, 4]
+
+for i, item in enumerate(items):
+    if item == 2:
+        items.remove(item)   # skips the second 2 silently
+```
+
+**Correct:**
+```python
+# dict — iterate over a copy of keys
+config = {"debug": True, "deprecatedKey": "val", "timeout": 30}
+
+for key in list(config.keys()):
+    if key.startswith("deprecated"):
+        del config[key]
+
+# Or build a new dict with dict comprehension (preferred for clarity)
+config = {k: v for k, v in config.items() if not k.startswith("deprecated")}
+
+# set — iterate over a copy
+seen = {1, 2, 3, 4, 5}
+to_remove = {item for item in seen if item % 2 == 0}
+seen -= to_remove
+
+# list — collect removals, apply after loop
+items = [1, 2, 2, 3, 4]
+items = [item for item in items if item != 2]   # list comprehension
+
+# Or for in-place modification, iterate in reverse
+items = [1, 2, 2, 3, 4]
+for i in range(len(items) - 1, -1, -1):
+    if items[i] == 2:
+        del items[i]
+```
+
+**Tools:** Ruff `E4702` (modified-iterating-dict), `E4703` (modified-iterating-set), `W4701` (modified-iterating-list), Pylint `modified_iteration` checker, flake8

package/skill-assets/sunlint-code-quality/rules/python/P015-prefer-fstrings.md

@@ -0,0 +1,61 @@
+---
+title: Prefer f-strings Over % and str.format()
+impact: MEDIUM
+impactDescription: f-strings introduced in Python 3.6 are more readable, faster at runtime, and catch errors at parse time rather than producing cryptic runtime errors from mismatched argument counts.
+tags: python, fstrings, readability, performance, quality, python3
+---
+
+## Prefer f-strings Over % and str.format()
+
+Python 3.6 introduced f-strings (`f"..."`) as the modern, preferred way to embed expressions in string literals. They are:
+- **More readable** — expression and string are co-located
+- **Faster** — evaluated at the bytecode level without function dispatch
+- **Safer** — syntax errors caught at parse time; no mismatched `%s` args
+- **More powerful** — support arbitrary expressions and format specs inline
+
+**Incorrect:**
+```python
+name = "Alice"
+score = 98.567
+items = ["apple", "banana"]
+
+# %-formatting (Python 2 style) — argument count mismatches cause runtime TypeError
+msg = "Hello, %s! Your score is %.2f" % (name, score)
+debug = "Processing %d items: %s" % len(items)    # runtime error: int not iterable
+
+# str.format() — verbose and error-prone with positional indices
+msg = "Hello, {}! Your score is {:.2f}".format(name, score)
+debug = "User {0} has {1} points ({0} is great)".format(name, score)
+```
+
+**Correct:**
+```python
+name = "Alice"
+score = 98.567
+user_id = 1042
+
+# f-strings — expression evaluated inline
+msg   = f"Hello, {name}! Your score is {score:.2f}"
+debug = f"Processing {len(items)} items: {items}"
+
+# Supports format specs
+padded  = f"{user_id:05d}"          # "01042"
+percent = f"{score / 100:.1%}"      # "98.6%"
+repr_v  = f"Object: {obj!r}"        # calls repr()
+
+# Multi-line f-string
+report = (
+    f"User: {name}\n"
+    f"Score: {score:.2f}\n"
+    f"Rank: {get_rank(score)}"
+)
+```
+
+**Exception — logging calls should NOT use f-strings:**
+```python
+# In logging, keep lazy % formatting for performance (see P009)
+logger.debug("Processing user %s", user_id)          # correct
+logger.debug(f"Processing user {user_id}")           # incorrect — always evaluates
+```
+
+**Tools:** Ruff `UP031` (printf-string-formatting), `UP032` (f-string), `G004` (logging-f-string), pyupgrade, flynt

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

@@ -0,0 +1,121 @@
+# Ruby on Rails Framework — SunLint Agent Guide
+
+> Priority directives for AI agents working on Rails projects.
+> Rule files: `.agent/skills/sunlint-code-quality/rules/`
+
+---
+
+## Critical Patterns — Apply Every Time
+
+### Input Filtering
+- **Always** whitelist params with `params.require(:model).permit(:field1, :field2)`
+- **Never** use `params[:model].to_unsafe_h`, `params.permit!`, or `Model.create(params[:model])`
+- See: `RR001-strong-parameters.md`
+
+### N+1 Queries
+- Any controller loading a collection that renders association data → add `includes(:relation)`
+- Use `eager_load(:relation)` when filtering by association columns (SQL `WHERE`)
+- Count in loops → use `counter_cache: true` + `model.relation_count` column
+- See: `RR002-eager-load-includes.md`, `RR011-counter-cache.md`
+
+### Authentication
+- `before_action :authenticate_user!` in `ApplicationController` — opt-out for public actions with `skip_before_action`
+- **Never** add authentication checks per-action (opt-in) — new actions are public by default
+- See: `RR008-before-action-auth.md`
+
+### Secrets
+- **Never** hardcode API keys, tokens, passwords in source files
+- `Rails.application.credentials.section[:key]` OR `ENV.fetch('KEY')` only
+- `config/master.key` and `config/credentials/*.key` must be in `.gitignore`
+- See: `RR009-rails-credentials.md`
+
+---
+
+## Architecture Patterns
+
+### Controller responsibility — thin controllers only
+Controllers do exactly: authenticate → authorize → parse strong params → call service → render response.
+```ruby
+def create
+  result = PlaceOrderService.new(user: current_user, params: order_params).call
+  if result.success?
+    render json: OrderResource.new(result.order), status: :created
+  else
+    render json: { errors: result.errors }, status: :unprocessable_entity
+  end
+end
+```
+See: `RR003-service-objects.md`
+
+### Service Objects
+- Business logic with multi-model writes, external calls, or branching → `app/services/` PORO
+- Expose one public method: `#call`
+- Return a `Result` struct: `Result = Struct.new(:value, :success?, :error, keyword_init: true)`
+- See: `RR003-service-objects.md`
+
+### Background Jobs
+- Email, external API calls, file processing, report generation → `ActiveJob` + `perform_later`
+- **Never** `Thread.new` in controllers, **never** inline slow work in the request cycle
+- Pass only primitive/serializable arguments to jobs (IDs, strings) — not AR objects
+- See: `RR004-active-job-background.md`
+
+### Pagination
+- Every collection endpoint must call `.page(params[:page]).per(n)` (Kaminari) or `pagy(...)` (Pagy)
+- **Never** `Model.all` without a page limit returned to the client
+- See: `RR005-pagination.md`
+
+### Bulk Data Iteration (jobs/scripts/rake)
+- `Model.all.each` → replace with `Model.find_each(batch_size: 500)`
+- Bulk updates → `Model.in_batches(of: 200) { |batch| batch.update_all(...) }`
+- See: `RR006-find-each-batches.md`
+
+### Query Scopes
+- Named conditions (`published`, `recent`, `by_author`) → `scope :name, -> { where(...) }` on model
+- **Never** inline `where('...')` chains in controllers — define a scope, call the scope
+- See: `RR010-scopes.md`
+
+### HTTP Status Codes
+- Every `render json:` must include `status:` — use Rails symbol names
+- `POST` success → `:created` (201), validation failure → `:unprocessable_entity` (422)
+- DELETE with no body → `head :no_content` (204)
+- Centralize `rescue_from ActiveRecord::RecordNotFound` → `:not_found` in ApplicationController
+- See: `RR007-http-status-codes.md`, `RR012-render-json-status.md`
+
+---
+
+## Run Commands
+
+```bash
+rails generate model   ModelName field:type
+rails generate service OrderService          # custom generator if installed
+rails generate job     ProcessExportJob
+rails generate migration AddCounterToTable
+
+rails test test/models/post_test.rb          # run specific test file
+rails test -n /test_name_pattern/            # run by name match
+bundle exec rspec spec/services/             # RSpec equivalent
+
+rails credentials:edit --environment production   # edit secrets
+rails credentials:show                            # view decrypted
+
+bundle exec rubocop --autocorrect            # lint + fix
+bundle exec brakeman                         # security scanner
+bundle exec bundle-audit check               # dependency CVE scanner
+```
+
+---
+
+## What NOT to do (quick reference)
+
+| ❌ Wrong | ✅ Correct |
+|---|---|
+| `params[:user].to_unsafe_h` | `params.require(:user).permit(:name, :email)` |
+| `Model.create(params[:model])` | `Model.create(user_params)` (permitted) |
+| `@posts = Post.all` (unbounded) | `@posts = Post.published.page(params[:page])` |
+| `post.comments.count` in loop | `counter_cache: true` → `post.comments_count` |
+| `Thread.new { ... }` | `MyJob.perform_later(...)` |
+| `after_create :call_stripe` on model | Service object wrapping the transaction |
+| Auth check per action (opt-in) | `before_action :authenticate_user!` in ApplicationController |
+| `render json: { errors: ... }` | `render json: { errors: ... }, status: :unprocessable_entity` |
+| `API_KEY = 'sk_live_...'` in source | `Rails.application.credentials.stripe[:api_key]` |
+| Inline `where('published = true')` in controller | `scope :published, -> { where(published: true) }` |

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR001-strong-parameters.md

@@ -0,0 +1,55 @@
+---
+title: "RR001 – Use Strong Parameters (params.require().permit())"
+impact: high
+impactDescription: "Mass assignment via permit() prevents unfiltered user input from modifying forbidden attributes such as roles, admin flags, or foreign keys."
+tags: [ruby, rails, security, input-validation]
+---
+
+# RR001 – Use Strong Parameters
+
+## Rule
+
+Always whitelist params with `require().permit()`. Never permit all params or bypass strong parameters.
+
+## Why
+
+`params.to_unsafe_h` and raw `params` bypass Rails' Mass Assignment protection. An attacker can inject `admin: true`, `role: 'admin'`, or arbitrary foreign keys.
+
+## Wrong
+
+```ruby
+# Bypasses strong parameters entirely
+def create
+  @user = User.create(params[:user].to_unsafe_h)
+end
+
+# Permits everything
+def user_params
+  params.require(:user).permit!
+end
+
+# Missing permit — may raise ForbiddenAttributesError or pass raw hash
+def create
+  @user = User.create(user_params: params[:user])
+end
+```
+
+## Correct
+
+```ruby
+def create
+  @user = User.create!(user_params)
+end
+
+private
+
+def user_params
+  params.require(:user).permit(:name, :email, :password, :password_confirmation)
+end
+```
+
+## Notes
+
+- `permit!` is only acceptable in internal admin scripts where input is completely trusted and audited.
+- Nested attributes need explicit permit: `permit(:name, addresses_attributes: [:street, :city])`.
+- Never store the result of `to_unsafe_h` into a model.

package/skill-assets/sunlint-code-quality/rules/ruby-rails/RR002-eager-load-includes.md

@@ -0,0 +1,51 @@
+---
+title: "RR002 – Prevent N+1 with includes/eager_load"
+impact: high
+impactDescription: "Unaddressed N+1 queries grow linearly with page size; a 100-row page fires 101 queries instead of 2."
+tags: [ruby, rails, performance, database]
+---
+
+# RR002 – Prevent N+1 with includes / eager_load
+
+## Rule
+
+Always eager-load associations when iterating over a collection. Use `includes`, `eager_load`, or `preload` based on whether a WHERE on the association is needed.
+
+## Why
+
+Accessing `post.author` inside an `.each` loop fires one SELECT per record — the classic N+1. Rails provides declarative eager loading to collapse N+1 into one extra query.
+
+## Wrong
+
+```ruby
+# N+1: fires 1 + N queries for authors
+@posts = Post.all
+# view iterates: @posts.each { |p| p.author.name }
+
+# N+1: fires 1 + N queries for comment counts
+@posts = Post.all
+# view: post.comments.count inside loop
+```
+
+## Correct
+
+```ruby
+# Two queries total: one for posts, one for authors
+@posts = Post.includes(:author).all
+
+# Three queries: posts + authors + tags
+@posts = Post.includes(:author, :tags).page(params[:page])
+
+# Need to filter by association column → use eager_load (LEFT JOIN)
+@posts = Post.eager_load(:author).where(authors: { verified: true })
+
+# Avoid count N+1 with counter_cache or withCount equivalent
+@posts = Post.includes(:comments)
+# or add counter_cache: true to the belongs_to and use post.comments_count
+```
+
+## Notes
+
+- `includes` automatically selects between `preload` (separate queries) and `eager_load` (LEFT JOIN). Prefer `includes` unless you explicitly need one over the other.
+- Use the `bullet` gem in development to surface N+1 automatically.
+- Nested associations: `Post.includes(comments: :author)`.