@cubis/foundry 0.3.67 → 0.3.68

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/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/workflows/agent-environment-setup/platforms/copilot/skills/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      |

package/workflows/workflows/agent-environment-setup/platforms/copilot/skills/ruby-pro/references/ruby-concurrency-and-testing.md

@@ -0,0 +1,190 @@
+# Ruby Concurrency and Testing
+
+## Ractor patterns (Ruby 3.0+)
+
+### Basic Ractor usage
+
+```ruby
+# CPU-bound parallel computation
+ractors = 4.times.map do |i|
+  Ractor.new(i) do |id|
+    # Each Ractor has its own isolated memory
+    heavy_computation(id)
+  end
+end
+
+results = ractors.map(&:take) # Collect results
+```
+
+- Ractors provide true parallelism by isolating memory between execution contexts.
+- Only shareable objects can be sent between Ractors: frozen objects, `Ractor.make_shareable(obj)`.
+- Use `Ractor.yield` / `Ractor.receive` for message-passing between Ractors.
+
+### Ractor constraints
+
+| Allowed                          | Not allowed                                   |
+| -------------------------------- | --------------------------------------------- |
+| Frozen strings, numbers, symbols | Mutable strings, arrays, hashes               |
+| `Ractor.make_shareable(obj)`     | Class variables shared across Ractors         |
+| `Ractor::MovedObject` transfer   | Global variables (`$stdout` is special-cased) |
+
+- Most gems are NOT Ractor-safe. Test thoroughly before using Ractors with external libraries.
+- Prefer Ractors for compute-heavy, isolated work (parsing, image processing, data transformation).
+
+## Fiber and Async patterns
+
+### Fiber-based concurrency
+
+```ruby
+require 'async'
+
+Async do |task|
+  # I/O-bound concurrent operations
+  response1 = task.async { HTTP.get("https://api.example.com/users") }
+  response2 = task.async { HTTP.get("https://api.example.com/posts") }
+
+  users = response1.wait
+  posts = response2.wait
+end
+```
+
+- Fibers run on a single thread — no thread-safety concerns for shared state.
+- Use the `async` gem for production fiber-based I/O concurrency.
+- Ideal for I/O-bound work: HTTP requests, database queries, file operations.
+- Not suitable for CPU-bound work — use Ractors or process-based parallelism instead.
+
+### Thread safety primitives
+
+```ruby
+mutex = Mutex.new
+counter = 0
+
+threads = 10.times.map do
+  Thread.new do
+    mutex.synchronize { counter += 1 }
+  end
+end
+threads.each(&:join)
+```
+
+- Use `Mutex#synchronize` for critical sections. Never call `lock`/`unlock` manually.
+- Use `Queue` for thread-safe producer/consumer patterns.
+- Use `Monitor` when you need reentrant locking (same thread can re-acquire the lock).
+- Prefer `Concurrent::Map` (from concurrent-ruby) over `Hash` with manual locking.
+
+## Background job patterns
+
+### Sidekiq best practices
+
+```ruby
+class UserNotificationJob
+  include Sidekiq::Job
+  sidekiq_options queue: :default, retry: 3
+
+  def perform(user_id, event_type)
+    user = User.find(user_id)
+    NotificationService.new(user).send(event_type)
+  end
+end
+```
+
+- Pass only primitive arguments (IDs, strings). Never pass ActiveRecord objects — they can't be serialized safely.
+- Set explicit retry counts. Use dead-letter queues for permanently failed jobs.
+- Keep jobs idempotent — they may run more than once due to retries.
+- Use separate queues for different priority levels (`:critical`, `:default`, `:low`).
+
+## Testing strategy
+
+### RSpec structure
+
+```ruby
+RSpec.describe UserService do
+  describe "#create" do
+    subject(:result) { described_class.new(repo:).create(params) }
+
+    let(:repo) { instance_double(UserRepository) }
+    let(:params) { { name: "Alice", email: "alice@example.com" } }
+
+    context "with valid params" do
+      before { allow(repo).to receive(:save).and_return(user) }
+      let(:user) { build(:user, **params) }
+
+      it { is_expected.to be_success }
+      it { expect(result.value).to have_attributes(name: "Alice") }
+    end
+
+    context "with duplicate email" do
+      before { allow(repo).to receive(:save).and_raise(UniqueViolation) }
+
+      it { is_expected.to be_failure }
+      it { expect(result.error).to include("already exists") }
+    end
+  end
+end
+```
+
+- Use `describe` for the class/method, `context` for scenarios, `it` for assertions.
+- Use `instance_double` for strict mocking — fails if the mocked method doesn't exist.
+- Use `let` for lazy setup, `let!` for eager setup, `before` for side effects.
+
+### Factory patterns
+
+```ruby
+FactoryBot.define do
+  factory :user do
+    name { Faker::Name.name }
+    email { Faker::Internet.email }
+    role { :member }
+
+    trait :admin do
+      role { :admin }
+    end
+
+    trait :with_posts do
+      after(:create) do |user|
+        create_list(:post, 3, author: user)
+      end
+    end
+  end
+end
+```
+
+- Use traits for variations instead of separate factories.
+- Prefer `build` (in-memory) over `create` (persisted) in unit tests for speed.
+- Use `build_stubbed` for the fastest option when persistence behavior isn't under test.
+
+## Gem dependency audit
+
+### Bundler security workflow
+
+```bash
+# Check for known vulnerabilities
+bundle audit check --update
+
+# List outdated gems (direct dependencies only)
+bundle outdated --only-explicit
+
+# Generate dependency graph
+bundle viz --format=svg
+```
+
+- Run `bundle audit` in CI. Block deploys on critical findings.
+- Update gems in small batches: `bundle update gem_name` + run full test suite.
+- Review changelogs before major version bumps — breaking changes often affect behavior silently.
+- Use `Gemfile` groups (`:development`, `:test`) to keep production dependencies minimal.
+
+### Type checking with Sorbet
+
+```ruby
+# typed: strict
+extend T::Sig
+
+sig { params(name: String, age: Integer).returns(User) }
+def create_user(name, age)
+  User.new(name:, age:)
+end
+```
+
+- Use `typed: strict` for new files, `typed: true` as a minimum for existing files.
+- Generate RBI files for gems: `tapioca gem` for type stubs.
+- Run `srb tc` in CI alongside tests.