@sun-asterisk/sunlint 1.3.48 → 1.3.49

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)`.

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.