rubyn-code 0.1.0

data/skills/ruby/enumerable_patterns.md

@@ -0,0 +1,168 @@
+# Ruby: Enumerable Patterns
+
+## Pattern
+
+Choose the most expressive Enumerable method for the operation. Ruby provides specific methods for specific transformations — using the right one makes code self-documenting and often more performant.
+
+```ruby
+users = [user_a, user_b, user_c, user_d]
+
+# TRANSFORMING: map when you want a new array of transformed elements
+emails = users.map(&:email)
+# => ["alice@example.com", "bob@example.com", ...]
+
+# FILTERING: select/reject for keeping/removing elements
+active_users = users.select(&:active?)
+inactive_users = users.reject(&:active?)
+
+# FINDING: find for the first match, detect is an alias
+admin = users.find { |u| u.role == :admin }
+
+# CHECKING: any?/all?/none? for boolean questions about the collection
+has_admins = users.any? { |u| u.role == :admin }
+all_confirmed = users.all?(&:confirmed?)
+no_banned = users.none?(&:banned?)
+
+# ACCUMULATING: each_with_object for building a new structure
+users_by_role = users.each_with_object({}) do |user, hash|
+  (hash[user.role] ||= []) << user
+end
+
+# COUNTING: tally for frequency counts (Ruby 2.7+)
+role_counts = users.map(&:role).tally
+# => { admin: 1, user: 3 }
+
+# GROUPING: group_by for categorizing
+by_plan = users.group_by(&:plan)
+# => { free: [user_a, user_c], pro: [user_b, user_d] }
+
+# FLATTENING + TRANSFORMING: flat_map when map would return nested arrays
+all_orders = users.flat_map(&:orders)
+# Instead of: users.map(&:orders).flatten
+
+# SORTING: sort_by for sorting by a derived value
+by_name = users.sort_by(&:name)
+by_newest = users.sort_by(&:created_at).reverse
+
+# CHUNKING: chunk for grouping consecutive elements
+log_lines.chunk { |line| line.start_with?("ERROR") }.each do |is_error, lines|
+  report_errors(lines) if is_error
+end
+
+# INDEXING: index_by (Rails) or to_h for key-value lookup
+users_by_id = users.index_by(&:id)
+# => { 1 => user_a, 2 => user_b, ... }
+
+# ZIPPING: zip for pairing elements from two arrays
+names = ["Alice", "Bob"]
+scores = [95, 87]
+paired = names.zip(scores)
+# => [["Alice", 95], ["Bob", 87]]
+```
+
+## Why This Is Good
+
+- **Self-documenting.** `users.select(&:active?)` reads like English. The method name tells you the intent — filtering. No comments needed.
+- **No intermediate state.** Each method returns a new array (or enumerator). No temporary variables, no mutation, no `<< item` inside a loop.
+- **Chainable.** Methods compose naturally: `users.select(&:active?).sort_by(&:name).map(&:email)` is a pipeline where each step is clear.
+- **Performance.** Specific methods like `any?` short-circuit (stop iterating once the answer is known). `flat_map` avoids creating an intermediate nested array. `tally` is a single pass instead of `group_by` + `transform_values(&:count)`.
+- **Symbol-to-proc shorthand.** `&:method_name` is idiomatic Ruby. Use it whenever the block is a single method call on the yielded element.
+
+## Anti-Pattern
+
+Using `each` with manual accumulation for everything:
+
+```ruby
+# Collecting results manually
+emails = []
+users.each do |user|
+  emails << user.email
+end
+
+# Filtering manually
+active_users = []
+users.each do |user|
+  if user.active?
+    active_users << user
+  end
+end
+
+# Building a hash manually
+users_by_role = {}
+users.each do |user|
+  if users_by_role[user.role]
+    users_by_role[user.role] << user
+  else
+    users_by_role[user.role] = [user]
+  end
+end
+
+# Counting manually
+admin_count = 0
+users.each do |user|
+  admin_count += 1 if user.role == :admin
+end
+```
+
+## Why This Is Bad
+
+- **Verbose.** 4 lines for what `map` does in 1. Multiply this across a codebase and you have thousands of unnecessary lines.
+- **Mutable state.** `emails = []` followed by `emails << ...` is imperative mutation. It's easy to accidentally push into the wrong array, skip the push, or modify the array elsewhere.
+- **Hides intent.** Reading `emails = []` followed by a loop, you have to trace through the loop body to understand "oh, this is collecting emails." With `map(&:email)`, the intent is immediate.
+- **Error-prone.** The manual hash building has a nil check that `group_by` handles automatically. The manual count is off-by-one prone. These bugs don't exist when you use the right method.
+- **Not chainable.** The result is a variable, not a method return. You can't compose it with another operation without assigning to yet another variable.
+
+## When To Apply
+
+- **Always.** There is no case where manual `each` + accumulation is better than the appropriate Enumerable method. This is idiomatic Ruby — it's expected.
+- **In ActiveRecord contexts** — prefer database operations (`pluck`, `where`, `group`, `count`) over loading records and using Ruby enumerables. But when you have the collection in memory already, use enumerables.
+
+## When NOT To Apply
+
+- **Don't chain excessively.** `users.select(&:active?).reject(&:banned?).sort_by(&:name).first(10).map(&:email)` is readable. Adding 3 more transformations is not. Break into named intermediate variables or methods if the chain exceeds 4-5 steps.
+- **Don't use enumerables on large database sets.** `User.all.select(&:active?)` loads every user into memory then filters in Ruby. Use `User.where(active: true)` to filter in the database.
+- **`each` is correct for side effects.** When the purpose is to DO something (send emails, update records, log output) rather than COMPUTE something, `each` is the right choice. Don't force `map` when you don't need the return value.
+
+## Edge Cases
+
+**`reduce` vs `each_with_object`:**
+Use `each_with_object` for building hashes and arrays. Use `reduce` for computing a single value (sum, product). The difference: `reduce` requires you to return the accumulator from every block; `each_with_object` doesn't.
+
+```ruby
+# each_with_object: cleaner for hash building
+users.each_with_object({}) { |u, h| h[u.id] = u.name }
+
+# reduce: cleaner for arithmetic
+order.line_items.reduce(0) { |sum, item| sum + item.total }
+
+# But for sums, just use .sum
+order.line_items.sum(&:total)
+```
+
+**`map` + `compact` vs `filter_map`:**
+Use `filter_map` (Ruby 2.7+) when the transformation might return nil and you want to skip nils:
+
+```ruby
+# Instead of
+users.map { |u| u.profile&.avatar_url }.compact
+
+# Use
+users.filter_map { |u| u.profile&.avatar_url }
+```
+
+**Lazy enumerables for large/infinite collections:**
+
+```ruby
+# Process a huge file without loading it all into memory
+File.open("huge.csv").lazy.map { |line| parse(line) }.select(&:valid?).first(100)
+```
+
+**`each_slice` and `each_cons` for batching:**
+
+```ruby
+# Process in batches of 100
+users.each_slice(100) { |batch| BulkEmailJob.perform_later(batch.map(&:id)) }
+
+# Sliding window of 3
+temperatures.each_cons(3) { |window| detect_trend(window) }
+```

data/skills/ruby/exception_handling.md

@@ -0,0 +1,199 @@
+# Ruby: Exception Handling
+
+## Pattern
+
+Rescue specific exceptions. Define custom exception hierarchies for your domain. Never use bare `rescue`. Use `retry` with limits. Always clean up resources in `ensure`.
+
+```ruby
+# Define a custom exception hierarchy for your domain
+module Rubyn
+  class Error < StandardError; end
+
+  class AuthenticationError < Error; end
+  class InsufficientCreditsError < Error; end
+  class RateLimitError < Error; end
+
+  class ApiError < Error
+    attr_reader :status_code, :response_body
+
+    def initialize(message, status_code:, response_body: nil)
+      @status_code = status_code
+      @response_body = response_body
+      super(message)
+    end
+  end
+end
+```
+
+```ruby
+# Rescue specific exceptions with appropriate handling
+class Orders::CreateService
+  def call
+    order = build_order
+    charge_payment(order)
+    order.save!
+    send_confirmation(order)
+    Result.new(success: true, order: order)
+  rescue Stripe::CardError => e
+    # Specific: payment failed, tell the user
+    Result.new(success: false, error: "Payment declined: #{e.message}")
+  rescue Stripe::RateLimitError => e
+    # Specific: transient, retry makes sense
+    retry_or_fail(e)
+  rescue ActiveRecord::RecordInvalid => e
+    # Specific: validation failed
+    Result.new(success: false, error: e.record.errors.full_messages.join(", "))
+  rescue Rubyn::InsufficientCreditsError
+    # Specific: domain error
+    Result.new(success: false, error: "Insufficient credits")
+  end
+end
+```
+
+```ruby
+# Retry pattern with exponential backoff and limit
+def fetch_with_retry(url, max_retries: 3)
+  retries = 0
+  begin
+    response = Faraday.get(url)
+    raise Rubyn::ApiError.new("Server error", status_code: response.status) if response.status >= 500
+    response
+  rescue Faraday::TimeoutError, Rubyn::ApiError => e
+    retries += 1
+    raise if retries > max_retries
+
+    sleep_time = (2**retries) + rand(0.0..0.5) # Exponential backoff with jitter
+    Rails.logger.warn("Retry #{retries}/#{max_retries} after #{e.class}: sleeping #{sleep_time}s")
+    sleep(sleep_time)
+    retry
+  end
+end
+```
+
+```ruby
+# Ensure for guaranteed cleanup
+def process_file(path)
+  file = File.open(path, "r")
+  parse_contents(file.read)
+rescue CSV::MalformedCSVError => e
+  Rails.logger.error("Malformed CSV: #{e.message}")
+  raise
+ensure
+  file&.close
+end
+
+# Better: use block form which handles cleanup automatically
+def process_file(path)
+  File.open(path, "r") do |file|
+    parse_contents(file.read)
+  end
+rescue CSV::MalformedCSVError => e
+  Rails.logger.error("Malformed CSV: #{e.message}")
+  raise
+end
+```
+
+## Why This Is Good
+
+- **Specific rescues handle specific failures.** A `Stripe::CardError` gets a user-facing message. A `Stripe::RateLimitError` gets a retry. A bare `rescue` would handle both the same way — hiding the card error behind a generic "something went wrong."
+- **Custom exceptions communicate domain intent.** `raise Rubyn::InsufficientCreditsError` is meaningful to anyone reading the code. `raise StandardError, "not enough credits"` is generic and uncatchable by type.
+- **Exception hierarchies enable selective catching.** `rescue Rubyn::Error` catches all domain exceptions. `rescue Rubyn::AuthenticationError` catches only auth failures. The hierarchy gives callers the granularity they need.
+- **Retry with backoff prevents cascading failures.** A transient network error triggers a retry with increasing delay, not an immediate failure or an infinite retry loop.
+- **`ensure` guarantees cleanup.** File handles, database connections, and temporary resources are always released, even when an exception occurs.
+
+## Anti-Pattern
+
+Bare rescue, swallowed exceptions, and rescue-driven flow control:
+
+```ruby
+# BAD: Bare rescue catches EVERYTHING including SyntaxError, NoMemoryError
+def create_order(params)
+  order = Order.create!(params)
+  charge_payment(order)
+  order
+rescue
+  nil
+end
+
+# BAD: Rescuing Exception (catches system signals, memory errors)
+begin
+  dangerous_operation
+rescue Exception => e
+  log(e.message)
+end
+
+# BAD: Using exceptions for flow control
+def find_user(email)
+  User.find_by!(email: email)
+rescue ActiveRecord::RecordNotFound
+  User.create!(email: email, name: "New User")
+end
+
+# BAD: Swallowing exceptions silently
+def send_notification(user)
+  NotificationService.call(user)
+rescue StandardError
+  # silently ignore all errors
+end
+```
+
+## Why This Is Bad
+
+- **Bare `rescue` catches `StandardError` and all subclasses.** This includes `NoMethodError`, `TypeError`, `NameError` — real bugs in your code that should crash loudly, not be silently swallowed. You're hiding bugs, not handling errors.
+- **Rescuing `Exception` catches signals.** `Interrupt` (Ctrl+C), `SignalException` (kill), `NoMemoryError`, and `SyntaxError` are all subclasses of `Exception`. Rescuing them makes your program unkillable and masks fatal errors.
+- **Exceptions for flow control are slow and misleading.** `find_by!` + `rescue RecordNotFound` is 10-100x slower than `find_by` + `nil?` check. Exceptions should be exceptional — unexpected failures, not expected branches.
+- **Silently swallowed exceptions are invisible bugs.** When `NotificationService.call` fails, nobody knows. The user doesn't get notified, no error is logged, no alert fires. The bug exists silently until someone investigates why notifications stopped.
+
+## When To Apply
+
+- **Always rescue specific exception classes.** Name the exception class you expect. If you can't name it, you don't understand the failure mode well enough to handle it.
+- **Custom exceptions for domain errors.** If your application has distinct failure modes (insufficient credits, rate limited, invalid API key), define exceptions for them.
+- **Retry for transient failures only.** Network timeouts, rate limits, and temporary server errors are retriable. Validation errors, authentication failures, and business logic violations are not.
+- **`ensure` for any resource that must be cleaned up.** Files, sockets, database connections, temporary directories. Or better — use block form methods that handle cleanup automatically (`File.open { }`, `ActiveRecord::Base.transaction { }`).
+
+## When NOT To Apply
+
+- **Don't rescue in every method.** Let exceptions propagate to the appropriate handler. A service object should raise; the controller or error middleware catches and renders the appropriate response.
+- **Don't define custom exceptions for one-off cases.** If an exception is only raised in one place and caught in one place, `StandardError` with a message is sufficient. Custom exceptions shine when the same error type is raised or caught in multiple places.
+- **Don't retry non-transient errors.** Retrying a `Stripe::CardError` (card declined) will fail every time. Retrying a `Stripe::RateLimitError` (temporary) makes sense.
+
+## Edge Cases
+
+**Re-raising after logging:**
+Use `raise` with no arguments to re-raise the current exception after logging it:
+
+```ruby
+rescue Rubyn::ApiError => e
+  Rails.logger.error("API failed: #{e.message}")
+  raise  # Re-raises the same exception with original backtrace
+end
+```
+
+**Wrapping third-party exceptions:**
+Convert external gem exceptions into your domain exceptions at the boundary:
+
+```ruby
+def fetch_data
+  ExternalApi.get("/data")
+rescue ExternalApi::Timeout => e
+  raise Rubyn::ApiError.new("External service timed out", status_code: 504)
+rescue ExternalApi::Unauthorized => e
+  raise Rubyn::AuthenticationError, "Invalid external API credentials"
+end
+```
+
+**Multiple rescue clauses — order matters:**
+Ruby checks rescue clauses top to bottom. Put specific exceptions before general ones:
+
+```ruby
+rescue Stripe::CardError => e          # Specific first
+  handle_card_error(e)
+rescue Stripe::StripeError => e         # General parent second
+  handle_stripe_error(e)
+rescue StandardError => e               # Catch-all last
+  handle_unexpected_error(e)
+end
+```
+
+**Exception in `ensure`:**
+If `ensure` raises an exception, it replaces the original exception. Keep `ensure` blocks simple and safe. Wrap cleanup in its own begin/rescue if it might fail.

data/skills/ruby/file_io.md

@@ -0,0 +1,217 @@
+# Ruby: File I/O
+
+## Pattern
+
+Use block forms for automatic resource cleanup, choose the right I/O method for the data size, and prefer standard library parsers (CSV, JSON, YAML) over manual parsing.
+
+### Reading Files
+
+```ruby
+# GOOD: Block form — file is automatically closed when block exits
+File.open("data.txt") do |file|
+  file.each_line { |line| process(line) }
+end
+
+# GOOD: Read entire file at once (small files only — loads into memory)
+content = File.read("config.yml")
+lines = File.readlines("data.txt", chomp: true)  # Array of lines, newlines stripped
+
+# GOOD: Stream large files line by line (constant memory)
+File.foreach("huge_log.txt") do |line|
+  next unless line.include?("ERROR")
+  log_error(line)
+end
+
+# GOOD: Read with encoding
+content = File.read("data.csv", encoding: "UTF-8")
+
+# BAD: Manual open without close
+file = File.open("data.txt")
+content = file.read
+# file.close  ← Easy to forget, especially if an exception occurs between open and close
+```
+
+### Writing Files
+
+```ruby
+# GOOD: Block form for writing
+File.open("output.txt", "w") do |file|
+  file.puts "Line 1"
+  file.puts "Line 2"
+end
+
+# GOOD: Write entire string at once
+File.write("output.txt", "Hello, world!")
+File.write("log.txt", "New entry\n", mode: "a")  # Append mode
+
+# GOOD: Atomic write — prevents partial writes on crash (Rails)
+require "fileutils"
+# Write to temp file, then rename (atomic on most filesystems)
+temp_path = "#{path}.tmp"
+File.write(temp_path, content)
+FileUtils.mv(temp_path, path)
+
+# Rails provides this built-in:
+File.atomic_write("config/settings.yml") do |file|
+  file.write(settings.to_yaml)
+end
+```
+
+### Temporary Files
+
+```ruby
+require "tempfile"
+
+# GOOD: Tempfile with block — auto-deleted when block exits
+Tempfile.create("report") do |temp|
+  temp.write(generate_csv_data)
+  temp.rewind
+  upload_to_s3(temp)
+end
+# File is deleted here
+
+# GOOD: Tempfile with specific extension
+Tempfile.create(["export", ".csv"]) do |temp|
+  temp.path  # => "/tmp/export20260320-12345.csv"
+  CSV.open(temp.path, "w") do |csv|
+    csv << ["name", "email"]
+    users.each { |u| csv << [u.name, u.email] }
+  end
+  send_email_with_attachment(temp.path)
+end
+```
+
+### CSV
+
+```ruby
+require "csv"
+
+# Reading
+CSV.foreach("orders.csv", headers: true) do |row|
+  Order.create!(
+    reference: row["reference"],
+    total: row["total"].to_i,
+    status: row["status"]
+  )
+end
+
+# Reading into array of hashes
+data = CSV.read("data.csv", headers: true).map(&:to_h)
+
+# Writing
+CSV.open("export.csv", "w") do |csv|
+  csv << %w[reference total status created_at]
+  orders.each do |order|
+    csv << [order.reference, order.total, order.status, order.created_at.iso8601]
+  end
+end
+
+# Generate CSV string (for send_data in controllers)
+csv_string = CSV.generate do |csv|
+  csv << %w[name email plan]
+  users.each { |u| csv << [u.name, u.email, u.plan] }
+end
+send_data csv_string, filename: "users-#{Date.current}.csv"
+```
+
+### JSON
+
+```ruby
+require "json"
+
+# Parsing
+data = JSON.parse(File.read("config.json"))
+data = JSON.parse(response.body, symbolize_names: true)  # Symbol keys
+
+# Generating
+json_string = { name: "Alice", orders: 5 }.to_json
+pretty_json = JSON.pretty_generate({ name: "Alice", orders: 5 })
+
+# Safe parsing (handle invalid JSON)
+begin
+  data = JSON.parse(input)
+rescue JSON::ParserError => e
+  Rails.logger.error("Invalid JSON: #{e.message}")
+  data = {}
+end
+```
+
+### YAML
+
+```ruby
+require "yaml"
+
+# SAFE: Permitted classes only (Ruby 3.1+ default)
+config = YAML.safe_load_file("config.yml", permitted_classes: [Date, Time, Symbol])
+
+# For Rails config files
+config = YAML.safe_load(
+  ERB.new(File.read("config/database.yml")).result,
+  permitted_classes: [Symbol],
+  aliases: true
+)
+
+# Writing
+File.write("output.yml", data.to_yaml)
+
+# DANGEROUS: Never use YAML.load on untrusted input — it can execute arbitrary code
+# YAML.load(user_input)  ← SECURITY VULNERABILITY
+# YAML.safe_load(user_input)  ← SAFE
+```
+
+### Path Handling
+
+```ruby
+# GOOD: Use Pathname or File.join — never string concatenation for paths
+require "pathname"
+
+path = Pathname.new("app/models")
+path / "order.rb"                    # => #<Pathname:app/models/order.rb>
+path.join("concerns", "sluggable.rb") # => #<Pathname:app/models/concerns/sluggable.rb>
+
+File.join("app", "models", "order.rb")  # => "app/models/order.rb" (cross-platform)
+
+# Useful Pathname methods
+path = Pathname.new("app/models/order.rb")
+path.exist?        # => true
+path.extname       # => ".rb"
+path.basename      # => #<Pathname:order.rb>
+path.dirname       # => #<Pathname:app/models>
+path.expand_path   # => #<Pathname:/home/user/project/app/models/order.rb>
+
+# BAD: String concatenation — breaks on different OS path separators
+"app" + "/" + "models" + "/" + "order.rb"
+```
+
+### Directory Operations
+
+```ruby
+# List files
+Dir.glob("app/models/**/*.rb")         # All .rb files recursively
+Dir.glob("spec/**/*_spec.rb")          # All spec files
+Dir["app/services/*.rb"]               # Shorthand for glob
+
+# Create directories
+FileUtils.mkdir_p("app/services/orders")  # Creates intermediate dirs
+
+# Check existence
+File.exist?("app/models/order.rb")
+File.directory?("app/services")
+File.file?("Gemfile")
+```
+
+## Why This Is Good
+
+- **Block forms guarantee cleanup.** Files are closed even if exceptions occur. No resource leaks.
+- **`File.foreach` streams.** Processing a 10GB log file uses constant memory, not 10GB.
+- **Standard library parsers handle edge cases.** CSV with quoted commas, JSON with unicode escapes, YAML with anchors — don't parse these manually.
+- **`YAML.safe_load` prevents RCE.** `YAML.load` can execute arbitrary Ruby code from crafted YAML. Always use `safe_load`.
+- **`Pathname` is cross-platform.** No hardcoded `/` separators that break on Windows.
+
+## When To Apply
+
+- **Always use block forms** for `File.open`, `Tempfile.create`, `CSV.open`.
+- **`File.foreach` for large files** (logs, data imports, CSVs over 1MB).
+- **`File.read` for small files** (config, templates, under 1MB).
+- **`YAML.safe_load` always** — never `YAML.load` on any input.
+- **`JSON.parse` with rescue** — external JSON may be malformed.