rubyn-code 0.1.0

data/skills/ruby/concurrency.md

@@ -0,0 +1,194 @@
+# Ruby: Concurrency
+
+## Pattern
+
+Ruby has multiple concurrency primitives: Threads for I/O parallelism, Fibers for cooperative concurrency, and Ractors (Ruby 3+) for true parallelism. Choose the right tool for the workload.
+
+### Threads — Best for I/O-Bound Work
+
+```ruby
+# Parallel HTTP requests — threads shine here because each waits on I/O
+urls = %w[
+  https://api.example.com/orders
+  https://api.example.com/users
+  https://api.example.com/products
+]
+
+results = urls.map do |url|
+  Thread.new(url) do |u|
+    Faraday.get(u).body
+  end
+end.map(&:value)  # .value blocks until the thread finishes
+
+# Thread pool for controlled concurrency
+require "concurrent-ruby"
+
+pool = Concurrent::FixedThreadPool.new(5)
+futures = urls.map do |url|
+  Concurrent::Future.execute(executor: pool) do
+    Faraday.get(url).body
+  end
+end
+results = futures.map(&:value)
+```
+
+```ruby
+# Thread-safe shared state with Mutex
+class Counter
+  def initialize
+    @count = 0
+    @mutex = Mutex.new
+  end
+
+  def increment
+    @mutex.synchronize { @count += 1 }
+  end
+
+  def value
+    @mutex.synchronize { @count }
+  end
+end
+
+counter = Counter.new
+threads = 10.times.map do
+  Thread.new { 1000.times { counter.increment } }
+end
+threads.each(&:join)
+counter.value  # => 10000 (always correct with Mutex)
+```
+
+### concurrent-ruby — Production-Grade Concurrency
+
+```ruby
+# Gemfile
+gem "concurrent-ruby"
+```
+
+```ruby
+# Thread-safe data structures
+require "concurrent"
+
+# Atomic values — no Mutex needed
+counter = Concurrent::AtomicFixnum.new(0)
+counter.increment
+counter.value  # => 1
+
+# Thread-safe hash
+cache = Concurrent::Map.new
+cache["key"] = "value"
+cache.fetch_or_store("key") { expensive_computation }
+
+# Promises for async pipelines
+result = Concurrent::Promise.fulfill("data")
+  .then { |data| transform(data) }
+  .then { |transformed| save(transformed) }
+  .rescue { |error| handle_error(error) }
+  .value  # Blocks until chain completes
+```
+
+### Fibers — Cooperative Concurrency
+
+```ruby
+# Fibers yield control explicitly — useful for generators and coroutines
+def id_generator
+  Fiber.new do
+    id = 0
+    loop do
+      Fiber.yield(id += 1)
+    end
+  end
+end
+
+gen = id_generator
+gen.resume  # => 1
+gen.resume  # => 2
+gen.resume  # => 3
+
+# Enumerator (built on Fibers) for lazy sequences
+def fibonacci
+  Enumerator.new do |y|
+    a, b = 0, 1
+    loop do
+      y.yield a
+      a, b = b, a + b
+    end
+  end
+end
+
+fibonacci.lazy.select(&:odd?).first(10)
+# => [1, 1, 3, 5, 13, 21, 55, 89, 233, 377]
+```
+
+### Batch Processing with `in_batches` + Threads
+
+```ruby
+# Process large datasets with controlled parallelism
+class BatchProcessor
+  def initialize(concurrency: 4)
+    @pool = Concurrent::FixedThreadPool.new(concurrency)
+  end
+
+  def process(scope, batch_size: 100, &block)
+    futures = []
+
+    scope.find_in_batches(batch_size: batch_size) do |batch|
+      futures << Concurrent::Future.execute(executor: @pool) do
+        batch.each { |record| block.call(record) }
+      end
+    end
+
+    futures.each(&:value!)  # Wait for all, re-raise exceptions
+  end
+
+  def shutdown
+    @pool.shutdown
+    @pool.wait_for_termination(30)
+  end
+end
+
+# Usage
+processor = BatchProcessor.new(concurrency: 4)
+processor.process(Order.where(status: :pending)) do |order|
+  Orders::ProcessService.call(order)
+end
+processor.shutdown
+```
+
+## Why This Is Good
+
+- **Threads for I/O.** 10 parallel HTTP requests complete in the time of 1 sequential request. Ruby's GVL releases during I/O, enabling true parallelism for network-bound work.
+- **`concurrent-ruby` is production-tested.** Thread pools, atomic values, promises, and thread-safe collections — battle-hardened by millions of Ruby apps.
+- **Mutex for correctness.** Shared mutable state without a Mutex causes race conditions. With a Mutex, operations are atomic and predictable.
+- **Fibers for generators.** Infinite sequences, lazy evaluation, and cooperative multitasking without threads.
+
+## Anti-Pattern
+
+Unprotected shared state or over-threading:
+
+```ruby
+# BAD: Race condition — no synchronization
+results = []
+threads = urls.map do |url|
+  Thread.new { results << Faraday.get(url).body }  # Array#<< is NOT thread-safe
+end
+threads.each(&:join)
+# results may be corrupted, missing items, or raise errors
+
+# FIX: Use thread-safe collection or collect from thread return values
+results = urls.map do |url|
+  Thread.new { Faraday.get(url).body }
+end.map(&:value)
+```
+
+## When To Apply
+
+- **I/O-bound work** — HTTP requests, file reads, database queries across multiple connections. Threads provide real speedup.
+- **Background processing** — Use `concurrent-ruby` thread pools for in-process parallelism.
+- **Lazy sequences** — Fibers and Enumerators for infinite or expensive sequences that are consumed incrementally.
+
+## When NOT To Apply
+
+- **CPU-bound work in MRI Ruby.** The Global VM Lock (GVL) prevents true parallel computation. Threads won't speed up math or data processing. Use Ractors or a separate process (via `parallel` gem).
+- **Simple sequential code.** If the operation takes 50ms, threading adds overhead without meaningful speedup.
+- **Rails request handling.** Puma already manages threads for you. Don't create threads inside controller actions — use background jobs instead.
+- **Avoid more than 10-20 threads.** Thread creation and context switching have overhead. Use a fixed thread pool, not unbounded `Thread.new`.

data/skills/ruby/data_struct_openstruct.md

@@ -0,0 +1,158 @@
+# Ruby: Data, Struct, and OpenStruct
+
+## Pattern
+
+Ruby provides three built-in ways to create simple data-holding classes. Choose the right one based on mutability needs and Ruby version.
+
+### Data (Ruby 3.2+) — Immutable Value Objects
+
+```ruby
+# Data.define creates a frozen, immutable value class
+Point = Data.define(:x, :y)
+Money = Data.define(:cents, :currency)
+DateRange = Data.define(:start_date, :end_date)
+
+# Creation
+point = Point.new(x: 10, y: 20)
+price = Money.new(cents: 19_99, currency: "USD")
+
+# Immutable — frozen by default
+point.x        # => 10
+point.frozen?  # => true
+point.x = 5   # => FrozenError
+
+# Equality by value
+Point.new(x: 1, y: 2) == Point.new(x: 1, y: 2)  # => true
+
+# Pattern matching
+case price
+in Money[cents: (0..99), currency: "USD"]
+  "Under a dollar"
+in Money[cents: (100..), currency: "USD"]
+  "A dollar or more"
+end
+
+# Add behavior with a block
+Money = Data.define(:cents, :currency) do
+  def to_s
+    "$#{format('%.2f', cents / 100.0)}"
+  end
+
+  def +(other)
+    raise ArgumentError, "Currency mismatch" unless currency == other.currency
+    self.class.new(cents: cents + other.cents, currency: currency)
+  end
+
+  def self.zero(currency = "USD")
+    new(cents: 0, currency: currency)
+  end
+end
+
+price = Money.new(cents: 10_00, currency: "USD")
+tax = Money.new(cents: 80, currency: "USD")
+total = price + tax
+total.to_s  # => "$10.80"
+```
+
+### Struct — Mutable Data Containers
+
+```ruby
+# Struct creates a mutable class with attribute accessors
+OrderSummary = Struct.new(:reference, :total, :status, keyword_init: true)
+
+summary = OrderSummary.new(reference: "ORD-001", total: 50_00, status: "pending")
+summary.reference  # => "ORD-001"
+summary.status = "shipped"  # Mutable — can change
+
+# Struct supports Enumerable
+summary.to_a       # => ["ORD-001", 50_00, "shipped"]
+summary.to_h       # => { reference: "ORD-001", total: 50_00, status: "shipped" }
+
+# Add methods
+Result = Struct.new(:success, :value, :error, keyword_init: true) do
+  def success?
+    success == true
+  end
+
+  def failure?
+    !success?
+  end
+end
+
+result = Result.new(success: true, value: order, error: nil)
+result.success?  # => true
+```
+
+### OpenStruct — Dynamic Attributes (Use Sparingly)
+
+```ruby
+# OpenStruct allows any attribute — no predefined structure
+config = OpenStruct.new(api_key: "sk-123", timeout: 30)
+config.api_key    # => "sk-123"
+config.new_field = "added dynamically"  # Any attribute, any time
+config.new_field  # => "added dynamically"
+
+# OpenStruct is SLOW — uses method_missing internally
+# ~10x slower than Struct for attribute access
+# ~100x slower than a plain class
+```
+
+## Decision Tree
+
+```
+Do you need a simple data container?
+├── Is the data immutable (value object)?
+│   ├── Ruby 3.2+? → Data.define
+│   └── Ruby < 3.2? → Struct.new with .freeze
+├── Is the data mutable?
+│   └── Struct.new (keyword_init: true)
+├── Are attributes dynamic/unknown at design time?
+│   └── OpenStruct (but consider a Hash instead)
+└── Does the object need complex behavior?
+    └── Write a full class
+```
+
+## When To Apply
+
+- **`Data.define`** for value objects: Money, Email, Coordinates, API responses, Result types. Anywhere immutability and value equality matter.
+- **`Struct`** for simple data transfer objects: search results, service return types, configuration that's built step by step.
+- **OpenStruct** for quick prototyping only. Replace with Struct or Data before code review.
+
+## When NOT To Apply
+
+- **ActiveRecord models.** They have their own attribute system. Don't wrap them in Struct/Data.
+- **Complex domain objects.** If the object has 5+ methods of behavior (not just accessors), write a class.
+- **Performance-critical paths.** OpenStruct is slow. In hot loops, use Struct or plain classes.
+- **OpenStruct in production code.** Its dynamic nature makes typos silent (`config.api_ky = "..."` creates a new attribute instead of raising). Struct catches this at construction time.
+
+## Edge Cases
+
+**Struct as a base class:**
+```ruby
+class User < Struct.new(:name, :email, keyword_init: true)
+  def greeting
+    "Hello, #{name}!"
+  end
+end
+```
+This works but is considered unusual. Prefer `Data.define` with a block or a plain class.
+
+**Freezing a Struct for immutability (pre-Ruby 3.2):**
+```ruby
+Config = Struct.new(:api_key, :timeout, keyword_init: true)
+config = Config.new(api_key: "sk-123", timeout: 30).freeze
+config.api_key = "new"  # => FrozenError
+```
+
+**Nested Data objects:**
+```ruby
+Address = Data.define(:street, :city, :state, :zip)
+Customer = Data.define(:name, :email, :address)
+
+customer = Customer.new(
+  name: "Alice",
+  email: "alice@example.com",
+  address: Address.new(street: "123 Main", city: "Austin", state: "TX", zip: "78701")
+)
+customer.address.city  # => "Austin"
+```

data/skills/ruby/debugging_profiling.md

@@ -0,0 +1,204 @@
+# Ruby: Debugging and Profiling
+
+## Pattern
+
+Use the right debugging tool for the problem: `debug` gem (Ruby 3.1+ built-in) for interactive debugging, logging for production visibility, and profiling tools to find performance bottlenecks.
+
+### Interactive Debugging (debug gem)
+
+```ruby
+# Ruby 3.1+ has `debug` built in — no gem needed
+# Add a breakpoint anywhere:
+def create_order(params)
+  order = Order.new(params)
+  binding.break  # Execution pauses here — inspect variables, step through code
+  order.save!
+  order
+end
+
+# Or use the shorter form
+def process(data)
+  debugger  # Same as binding.break
+  transform(data)
+end
+```
+
+Debug session commands:
+```
+# In the debug console:
+(rdbg) p order           # Print variable
+(rdbg) pp order.errors   # Pretty-print
+(rdbg) n                 # Next line (step over)
+(rdbg) s                 # Step into method
+(rdbg) c                 # Continue execution
+(rdbg) info locals       # Show all local variables
+(rdbg) bt                # Backtrace
+(rdbg) watch @total      # Break when @total changes
+(rdbg) break Order#save  # Break when Order#save is called
+```
+
+### Pry (Popular Alternative)
+
+```ruby
+# Gemfile
+gem "pry", group: [:development, :test]
+gem "pry-byebug", group: [:development, :test]  # Adds step/next/continue
+
+# Usage
+def calculate_total(items)
+  subtotal = items.sum(&:price)
+  binding.pry  # Drops into Pry REPL
+  subtotal * 1.08
+end
+
+# Pry commands:
+# ls object       — list methods
+# cd object       — change context into object
+# show-method     — show source code of a method
+# whereami        — show current location
+# next/step/continue — navigation (with pry-byebug)
+```
+
+### Logging Best Practices
+
+```ruby
+# Rails logger levels: debug < info < warn < error < fatal
+class Orders::CreateService
+  def call(params, user)
+    Rails.logger.info("[Orders::CreateService] Starting for user=#{user.id}")
+
+    order = user.orders.build(params)
+    unless order.valid?
+      Rails.logger.warn("[Orders::CreateService] Validation failed: #{order.errors.full_messages}")
+      return Result.failure(order.errors)
+    end
+
+    order.save!
+    Rails.logger.info("[Orders::CreateService] Created order=#{order.id} total=#{order.total}")
+
+    Result.success(order)
+  rescue StandardError => e
+    Rails.logger.error("[Orders::CreateService] Failed: #{e.class}: #{e.message}")
+    Rails.logger.debug(e.backtrace.first(10).join("\n"))
+    raise
+  end
+end
+
+# Tagged logging — adds context to every log line
+Rails.logger = ActiveSupport::TaggedLogging.new(Logger.new($stdout))
+Rails.logger.tagged("OrderService", "user:#{user.id}") do
+  Rails.logger.info("Processing order")
+  # => [OrderService] [user:42] Processing order
+end
+
+# Structured logging for production (JSON)
+# Gemfile
+gem "lograge"
+
+# config/environments/production.rb
+config.lograge.enabled = true
+config.lograge.formatter = Lograge::Formatters::Json.new
+config.lograge.custom_payload do |controller|
+  { user_id: controller.current_user&.id }
+end
+# Output: {"method":"POST","path":"/orders","status":201,"duration":45.2,"user_id":42}
+```
+
+### Performance Profiling
+
+```ruby
+# Benchmark a block
+require "benchmark"
+
+time = Benchmark.measure do
+  Order.where(status: :pending).find_each { |o| process(o) }
+end
+puts time  # => 0.120000   0.030000   0.150000 (  0.152345)
+
+# Compare approaches
+Benchmark.bm(20) do |x|
+  x.report("find_each:") { Order.pending.find_each { |o| o.total } }
+  x.report("pluck:") { Order.pending.pluck(:total) }
+  x.report("in_batches:") { Order.pending.in_batches.each_record { |o| o.total } }
+end
+
+# Memory profiling
+# Gemfile
+gem "memory_profiler", group: :development
+
+report = MemoryProfiler.report do
+  users = User.all.to_a
+  users.map(&:email)
+end
+report.pretty_print
+# Shows: allocated memory, retained memory, allocation by gem/file/location
+
+# rack-mini-profiler for web requests
+# Gemfile
+gem "rack-mini-profiler", group: :development
+
+# Shows a speed badge on every page with:
+# - Total request time
+# - SQL query count and time
+# - Memory usage
+# - Flamegraph link
+```
+
+### Finding N+1 Queries
+
+```ruby
+# Bullet gem detects N+1 in development
+# Gemfile
+gem "bullet", group: :development
+
+# config/environments/development.rb
+config.after_initialize do
+  Bullet.enable = true
+  Bullet.alert = true          # Browser popup
+  Bullet.rails_logger = true   # Log to Rails log
+  Bullet.add_footer = true     # Badge in page footer
+end
+
+# strict_loading (Rails 6.1+) — raises on lazy loading
+class Order < ApplicationRecord
+  self.strict_loading_by_default = true
+end
+
+# Or per-query
+Order.strict_loading.includes(:line_items).each do |order|
+  order.line_items  # Works — preloaded
+  order.user        # Raises! Not preloaded
+end
+```
+
+### Production Debugging
+
+```ruby
+# Rails console in production
+# RAILS_ENV=production rails console
+
+# Safe read-only queries
+ActiveRecord::Base.connected_to(role: :reading) do
+  Order.where(status: :pending).count
+end
+
+# Sandbox mode — rolls back all changes on exit
+# rails console --sandbox
+
+# Quick diagnostics
+Rails.logger.level = :debug  # Temporarily increase verbosity
+ActiveRecord::Base.logger = Logger.new($stdout)  # See all SQL
+```
+
+## When To Apply
+
+- **`debugger`/`binding.pry` for investigation.** When you don't understand why code behaves a certain way, stop execution and inspect state.
+- **Logging for production.** Always log: service entry/exit, errors with context, and performance metrics. Never log: passwords, API keys, or PII.
+- **Profiling before optimizing.** Measure first. The bottleneck is almost never where you think it is.
+- **Bullet/strict_loading in development.** Catch N+1s before they reach production.
+
+## When NOT To Apply
+
+- **Don't leave `debugger` calls in committed code.** Use `binding.pry` and `debugger` for local debugging only. CI should catch any that slip through.
+- **Don't log everything.** Debug-level logging for every method call creates noise. Log at the right level: info for normal flow, warn for recoverable issues, error for failures.
+- **Don't optimize without profiling.** "I think this is slow" → profile it → optimize the actual bottleneck.