@cubis/foundry 0.3.71 → 0.3.72

package/workflows/powers/ruby-pro/references/modern-ruby-features.md

@@ -0,0 +1,189 @@
+# Modern Ruby Features
+
+## Pattern Matching (Ruby 3.0+)
+
+```ruby
+# case/in pattern matching
+case response
+in { status: 200, body: { data: Array => items } }
+  process_items(items)
+in { status: 200, body: { data: Hash => item } }
+  process_item(item)
+in { status: 404 }
+  raise NotFoundError
+in { status: (500..) }
+  raise ServerError, "Status: #{response[:status]}"
+end
+
+# Find pattern (Ruby 3.0) — match element in array
+case users
+in [*, { role: "admin", name: String => admin_name }, *]
+  puts "Found admin: #{admin_name}"
+end
+
+# Pin operator — match against existing variable
+expected_status = 200
+case response
+in { status: ^expected_status }
+  puts "OK"
+end
+
+# Rightward assignment with pattern
+response => { status:, body: { data: } }
+# status and data are now local variables
+
+# Guard clauses
+case user
+in { age: (18..) => age } if age < 65
+  puts "Working age: #{age}"
+end
+```
+
+## Data.define (Ruby 3.2+)
+
+```ruby
+# Immutable value objects — replacement for Struct
+Point = Data.define(:x, :y)
+point = Point.new(x: 1, y: 2)
+point.x      # => 1
+point.frozen? # => true
+# point.x = 3 # NoMethodError — immutable
+
+# With custom methods
+Money = Data.define(:amount, :currency) do
+  def to_s = "#{format('%.2f', amount / 100.0)} #{currency}"
+
+  def +(other)
+    raise ArgumentError, "Currency mismatch" unless currency == other.currency
+    Money.new(amount: amount + other.amount, currency: currency)
+  end
+end
+
+price = Money.new(amount: 1999, currency: "USD")
+tax = Money.new(amount: 160, currency: "USD")
+total = price + tax  # Money(amount: 2159, currency: "USD")
+
+# Pattern matching with Data
+case point
+in Point[x: 0, y: 0]
+  "origin"
+in Point[x: 0, y:]
+  "on y-axis at #{y}"
+in Point[x:, y: 0]
+  "on x-axis at #{x}"
+in Point[x:, y:]
+  "(#{x}, #{y})"
+end
+```
+
+## Numbered Block Parameters (Ruby 2.7+)
+
+```ruby
+# _1, _2, etc. for simple blocks
+[1, 2, 3].map { _1 * 2 }          # => [2, 4, 6]
+{ a: 1, b: 2 }.map { "#{_1}=#{_2}" } # => ["a=1", "b=2"]
+
+# Best for simple one-liners; use named params for complex blocks
+users.select { _1.active? && _1.age >= 18 }
+```
+
+## Endless Method Definition (Ruby 3.0+)
+
+```ruby
+# Single-expression methods without end
+def full_name = "#{first_name} #{last_name}"
+def adult? = age >= 18
+def area = Math::PI * radius**2
+
+# With arguments
+def greet(name) = "Hello, #{name}!"
+```
+
+## Hash Shorthand (Ruby 3.1+)
+
+```ruby
+# Omit value when key and variable name match
+name = "Alice"
+age = 30
+role = :admin
+
+# Before
+user = { name: name, age: age, role: role }
+
+# After — shorthand
+user = { name:, age:, role: }
+```
+
+## Enumerator::Product and Composable Enumerators
+
+```ruby
+# Enumerator.product (Ruby 3.2+)
+colors = [:red, :blue]
+sizes = [:s, :m, :l]
+Enumerator::Product.new(colors, sizes).each do |color, size|
+  puts "#{color}-#{size}" # red-s, red-m, red-l, blue-s, blue-m, blue-l
+end
+
+# Lazy enumerators for large/infinite sequences
+(1..).lazy
+  .select { _1.odd? }
+  .map { _1 ** 2 }
+  .first(5)  # => [1, 9, 25, 49, 81]
+```
+
+## Frozen String Literals
+
+```ruby
+# frozen_string_literal: true
+
+# All string literals are frozen (immutable) — less GC pressure
+greeting = "hello"
+greeting << " world" # FrozenError raised
+
+# Explicit mutable strings
+mutable = String.new("hello")
+mutable << " world"  # OK
+
+# Or duplicate
+mutable = "hello".dup
+mutable << " world"  # OK
+```
+
+## Refinements
+
+```ruby
+# Safe monkey-patching — scoped to file/module
+module StringExtensions
+  refine String do
+    def to_slug
+      downcase.strip.gsub(/\s+/, '-').gsub(/[^\w-]/, '')
+    end
+  end
+end
+
+# Only active where explicitly used
+using StringExtensions
+"Hello World!".to_slug # => "hello-world"
+# Outside this file, String#to_slug doesn't exist
+```
+
+## Error Handling Improvements
+
+```ruby
+# Exception#detailed_message (Ruby 3.2+)
+class ApiError < StandardError
+  def initialize(status, body)
+    @status = status
+    @body = body
+    super("API error: #{status}")
+  end
+
+  def detailed_message(highlight: false, **)
+    msg = "API Error #{@status}: #{@body.first(200)}"
+    highlight ? "\e[1;31m#{msg}\e[0m" : msg
+  end
+end
+
+# Syntax sugar for rescue in blocks
+result = Integer("abc") rescue nil  # inline rescue (use sparingly)
+```

package/workflows/powers/ruby-pro/references/object-design-patterns.md

@@ -0,0 +1,220 @@
+# Object Design Patterns
+
+## Service Objects
+
+```ruby
+# Single-purpose service with call interface
+class CreateOrder
+  def initialize(order_repo:, pricing:, notifier:)
+    @order_repo = order_repo
+    @pricing = pricing
+    @notifier = notifier
+  end
+
+  def call(customer:, items:)
+    total = @pricing.calculate(items)
+    order = Order.new(customer:, items:, total:)
+
+    @order_repo.save(order)
+    @notifier.order_created(order)
+
+    Result.success(order)
+  rescue Pricing::Error => e
+    Result.failure(e.message)
+  end
+end
+
+# Usage
+result = CreateOrder.new(
+  order_repo: OrderRepository.new,
+  pricing: PricingService.new,
+  notifier: EmailNotifier.new,
+).call(customer: current_user, items: cart_items)
+
+case result
+in Result[success: true, value: order]
+  render json: order, status: :created
+in Result[success: false, error: message]
+  render json: { error: message }, status: :unprocessable_entity
+end
+```
+
+## Value Objects with Data.define
+
+```ruby
+Email = Data.define(:address) do
+  def initialize(address:)
+    raise ArgumentError, "Invalid email" unless address.match?(/\A[^@]+@[^@]+\z/)
+    super(address: address.downcase.strip)
+  end
+
+  def domain = address.split("@").last
+  def to_s = address
+end
+
+DateRange = Data.define(:start_date, :end_date) do
+  def initialize(start_date:, end_date:)
+    raise ArgumentError, "Start must be before end" if start_date > end_date
+    super
+  end
+
+  def days = (end_date - start_date).to_i
+  def include?(date) = (start_date..end_date).cover?(date)
+end
+```
+
+## Result Monad
+
+```ruby
+# Simple Result type for expected failures
+class Result
+  attr_reader :value, :error
+
+  def initialize(success:, value: nil, error: nil)
+    @success = success
+    @value = value
+    @error = error
+    freeze
+  end
+
+  def self.success(value) = new(success: true, value:)
+  def self.failure(error) = new(success: false, error:)
+
+  def success? = @success
+  def failure? = !@success
+
+  def map
+    return self if failure?
+    Result.success(yield(value))
+  end
+
+  def flat_map
+    return self if failure?
+    yield(value)
+  end
+
+  # Pattern matching support
+  def deconstruct_keys(keys)
+    { success: @success, value: @value, error: @error }
+  end
+end
+
+# Chainable operations
+result = validate_input(params)
+  .flat_map { |input| find_user(input[:user_id]) }
+  .flat_map { |user| authorize(user, :create_order) }
+  .flat_map { |user| create_order(user, params[:items]) }
+  .map { |order| OrderSerializer.new(order).as_json }
+```
+
+## Query Objects
+
+```ruby
+# Encapsulate complex database queries
+class ActiveOrdersQuery
+  def initialize(scope = Order.all)
+    @scope = scope
+  end
+
+  def call(filters = {})
+    result = @scope.where(status: :active)
+
+    result = result.where(customer_id: filters[:customer_id]) if filters[:customer_id]
+    result = result.where("total >= ?", filters[:min_total]) if filters[:min_total]
+    result = result.where("created_at >= ?", filters[:since]) if filters[:since]
+    result = result.order(created_at: :desc)
+
+    result
+  end
+end
+
+# Usage
+orders = ActiveOrdersQuery.new.call(
+  customer_id: 42,
+  min_total: 100,
+  since: 30.days.ago,
+)
+```
+
+## Composition Over Inheritance
+
+```ruby
+# BAD — deep inheritance
+class AdminUser < PremiumUser < User < BaseModel
+
+# GOOD — modules for shared behavior
+module Authenticatable
+  def authenticate(password)
+    BCrypt::Password.new(password_digest) == password
+  end
+end
+
+module Auditable
+  def self.included(base)
+    base.before_save :record_audit_trail
+  end
+
+  private
+
+  def record_audit_trail
+    AuditLog.record(self, changes)
+  end
+end
+
+class User
+  include Authenticatable
+  include Auditable
+
+  # User-specific behavior
+end
+```
+
+## Decorator Pattern
+
+```ruby
+# SimpleDelegator for transparent decoration
+class LoggingOrderService < SimpleDelegator
+  def initialize(service, logger:)
+    super(service)
+    @logger = logger
+  end
+
+  def create(params)
+    @logger.info("Creating order: #{params.inspect}")
+    result = super
+    @logger.info("Order created: #{result.value&.id}")
+    result
+  end
+end
+
+# Wrap the real service
+service = LoggingOrderService.new(
+  CreateOrder.new(order_repo:, pricing:, notifier:),
+  logger: Rails.logger,
+)
+```
+
+## Policy Objects
+
+```ruby
+# Encapsulate authorization logic
+class OrderPolicy
+  def initialize(user, order)
+    @user = user
+    @order = order
+  end
+
+  def show? = owner? || admin?
+  def update? = owner? && @order.pending?
+  def cancel? = (owner? || admin?) && @order.cancellable?
+  def refund? = admin? && @order.paid?
+
+  private
+
+  def owner? = @user.id == @order.customer_id
+  def admin? = @user.admin?
+end
+
+# Usage
+raise Forbidden unless OrderPolicy.new(current_user, order).cancel?
+```

package/workflows/powers/ruby-pro/references/performance-and-profiling.md

@@ -0,0 +1,224 @@
+# Performance and Profiling
+
+## Profiling Workflow
+
+1. **Reproduce** — identify the slow path with real workload or representative benchmark.
+2. **Profile** — CPU time, memory allocations, or GC pressure depending on the symptom.
+3. **Identify hotspot** — focus on the top contributor, not scattered micro-optimizations.
+4. **Change one thing** — benchmark before and after.
+5. **Verify correctness** — run tests after every optimization.
+
+## CPU Profiling with Stackprof
+
+```ruby
+# Gemfile
+gem "stackprof", group: [:development, :test]
+
+# Sample CPU usage
+StackProf.run(mode: :cpu, out: "tmp/stackprof-cpu.dump") do
+  perform_expensive_operation
+end
+
+# View results
+# stackprof tmp/stackprof-cpu.dump --text
+# stackprof tmp/stackprof-cpu.dump --method 'OrderService#calculate'
+# stackprof tmp/stackprof-cpu.dump --flamegraph > tmp/flamegraph.json
+
+# Wall-clock profiling (includes I/O wait time)
+StackProf.run(mode: :wall, interval: 1000) do
+  fetch_external_data
+end
+
+# Object allocation profiling
+StackProf.run(mode: :object) do
+  process_batch(items)
+end
+```
+
+## Memory Profiling
+
+```ruby
+# Gemfile
+gem "memory_profiler", group: [:development, :test]
+
+# Profile memory allocations
+report = MemoryProfiler.report do
+  100.times { build_response(data) }
+end
+
+report.pretty_print
+# Shows: allocated memory by gem, file, location, class
+# Retained memory (memory that survived GC)
+
+# Derailed benchmarks for Rails boot and request memory
+# gem "derailed_benchmarks"
+# bundle exec derailed bundle:mem      # memory at boot
+# bundle exec derailed exec perf:mem   # memory per request
+```
+
+## Benchmarking
+
+```ruby
+require "benchmark/ips"
+
+Benchmark.ips do |x|
+  data = (1..1000).to_a
+
+  x.report("each + push") do
+    result = []
+    data.each { |i| result.push(i * 2) }
+  end
+
+  x.report("map") do
+    data.map { |i| i * 2 }
+  end
+
+  x.report("map with _1") do
+    data.map { _1 * 2 }
+  end
+
+  x.compare!
+end
+```
+
+## YJIT (Ruby 3.2+)
+
+```bash
+# Enable YJIT at startup — significant performance improvement
+ruby --yjit app.rb
+
+# Or via environment variable
+RUBY_YJIT_ENABLE=1 bundle exec rails server
+
+# YJIT stats (development)
+ruby --yjit-stats app.rb
+# Shows: compiled methods, inline cache hits, code size
+
+# In Puma/Unicorn config
+# YJIT is enabled by default in Ruby 3.3+ for processes with enough memory
+```
+
+```ruby
+# Check YJIT status at runtime
+RubyVM::YJIT.enabled?  # => true/false
+RubyVM::YJIT.stats     # hash of compilation stats
+```
+
+## GC Tuning
+
+```bash
+# Environment variables for GC tuning
+RUBY_GC_HEAP_INIT_SLOTS=600000      # initial heap size (reduce GC early in boot)
+RUBY_GC_HEAP_FREE_SLOTS_MIN_RATIO=0.20
+RUBY_GC_HEAP_FREE_SLOTS_MAX_RATIO=0.40
+
+# Malloc-based GC tuning
+RUBY_GC_MALLOC_LIMIT=128000000       # 128MB before major GC
+RUBY_GC_OLDMALLOC_LIMIT=128000000
+```
+
+```ruby
+# Monitor GC in production
+GC.stat
+# => { count: 42, heap_allocated_pages: 150, total_allocated_objects: 5000000, ... }
+
+# Disable GC during critical sections (use sparingly)
+GC.disable
+critical_operation
+GC.enable
+GC.start  # trigger GC at convenient point
+```
+
+## String Optimization
+
+```ruby
+# frozen_string_literal: true
+
+# Frozen strings are deduplicated — one object for identical literals
+greeting = "hello"  # same object every time this line runs
+
+# String interpolation creates new strings — cache when reused
+# BAD — new string every iteration
+items.each do |item|
+  cache_key = "item:#{item.id}:data"  # new string each time
+  cache.get(cache_key)
+end
+
+# BETTER — use frozen format
+FORMAT = "item:%d:data"
+items.each do |item|
+  cache_key = format(FORMAT, item.id)
+  cache.get(cache_key)
+end
+
+# Use symbols for hash keys — deduplicated by runtime
+# GOOD: { name: "Alice" }
+# BAD:  { "name" => "Alice" }  # string key allocated each time
+```
+
+## Enumerable Patterns
+
+```ruby
+# Prefer Enumerable methods over manual loops
+
+# Lazy evaluation for large collections
+File.open("huge.csv").each_line
+  .lazy
+  .reject { _1.start_with?("#") }
+  .map { _1.strip.split(",") }
+  .select { |cols| cols[2].to_i > 100 }
+  .first(10)
+
+# each_with_object for building results
+totals = orders.each_with_object(Hash.new(0)) do |order, sums|
+  sums[order.category] += order.total
+end
+
+# chunk/slice for batch processing
+large_dataset.each_slice(1000) do |batch|
+  Model.insert_all(batch.map(&:attributes))
+end
+
+# tally for counting
+["a", "b", "a", "c", "b", "a"].tally
+# => {"a" => 3, "b" => 2, "c" => 1}
+
+# filter_map — map + compact in one pass
+users.filter_map { |u| u.email if u.active? }
+```
+
+## Caching
+
+```ruby
+# Memoization — instance-level caching
+def expensive_result
+  @expensive_result ||= compute_expensive_thing
+end
+
+# Memoize nil/false safely
+def nullable_result
+  return @nullable_result if defined?(@nullable_result)
+  @nullable_result = potentially_nil_computation
+end
+
+# Application-level caching
+Rails.cache.fetch("user:#{id}:profile", expires_in: 1.hour) do
+  UserProfile.new(user).compute
+end
+
+# Cache key fingerprinting
+def cache_key
+  [self.class.name, id, updated_at.to_i].join("/")
+end
+```
+
+## Common Anti-Patterns
+
+| Anti-pattern                   | Impact                      | Fix                                      |
+| ------------------------------ | --------------------------- | ---------------------------------------- |
+| N+1 queries                    | O(n) DB calls per list      | `includes` / `preload` / `eager_load`    |
+| String concatenation in loop   | O(n²) allocations           | `StringIO` or `Array#join`               |
+| `OpenStruct` for data          | 10x slower than Struct/Data | `Data.define` or `Struct`                |
+| `method_missing` without cache | Method lookup on every call | Define methods dynamically on first call |
+| Loading entire table           | Memory exhaustion           | `find_each` / `in_batches`               |
+| No connection pooling          | Exhausted connections       | Configure pool size in database.yml      |