crspec 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 649f2c29f7f22f52d1291691f9c96c2c9718ab907c38e8ea27604fab5ec9ef8f
+  data.tar.gz: cfaac3973542770dc81f08c921bb29b054ed64f3dae0913ca75b175d42438242
+SHA512:
+  metadata.gz: 85dc17da65b7d4bb59766cb7a00220f9009fec3b4e869969d3dde17fbafe7c8f63b190b083d2fbd243f3e6b3e02470f0e3076a9142b38b5d5e65ddb7ad595894
+  data.tar.gz: '0257282967b6ed5ca718bd01cf7329a920f8fca18266d44a59e196453bbd8db2d0bdaf52e646b9553cf86eed375c2f00c7e33139435d36876ae43bb4ddbd689a'

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-07-29
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Aboobacker MK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,180 @@
+# Crspec
+
+**Crspec** is a next-generation concurrent, fiber-isolated Ruby testing framework ecosystem. By leveraging Ruby 3.2+ **Fiber Storage** (`Fiber[:key]`), fiber-aware method interceptors, non-blocking fiber schedulers, and `ruby/prism` AST transpilation, Crspec achieves ultra-fast concurrent test execution while maintaining full syntax compatibility with traditional RSpec suites.
+
+---
+
+## Key Features
+
+- **Fiber Storage Context Isolation**: Solves legacy thread-local (`Thread.current`) state leakage by routing all execution metadata and `let` memoization through inherited Fiber storage (`Fiber[:crspec_execution_context]`).
+- **Fiber-Aware Mocking (`crspec-mock`)**: Prevents mock registry corruption across parallel tests using prepended method interceptors bound to `Fiber[:crspec_mock_space]`.
+- **Rails Connection Leasing & Parallel Testing (`crspec-rails`)**: Leases database connections per example fiber (`ActiveRecord::Base.lease_connection`), handles savepoint transaction strategies (`SAVEPOINT ex_root`), and integrates with Rails parallel worker suites (`Crspec::Rails::Parallel`).
+- **Prism-Based AST Transpiler (`crspec-transpiler`)**: Automated migration tool using `ruby/prism` C-parser to convert existing RSpec codebases to Crspec syntax and flag thread-unsafe constructs like `before(:all)`.
+- **Concurrent Execution Kernel**: Multi-threaded worker pool integrated with non-blocking fiber schedulers (`Async::Scheduler`).
+
+---
+
+## Installation
+
+Add `crspec` to your application's `Gemfile`:
+
+```ruby
+gem "crspec", github: "crspec/crspec"
+```
+
+Then install via Bundler (or `mise`):
+
+```bash
+mise exec -- bundle install
+```
+
+---
+
+## Writing Specs
+
+`crspec` provides a familiar RSpec-style DSL for structuring example groups and expectations:
+
+```ruby
+require "crspec"
+
+Crspec.describe User, type: :model do
+  let(:valid_attributes) { { name: "Jane Doe", email: "jane@example.com" } }
+  subject(:user) { User.new(valid_attributes) }
+
+  it "validates primary attributes" do
+    expect(user.valid?).to be(true)
+  end
+
+  context "when email is omitted" do
+    let(:valid_attributes) { { name: "Jane Doe", email: nil } }
+
+    it "flags validation errors" do
+      expect(user.valid?).to be(false)
+      expect(user.errors[:email]).to include("can't be blank")
+    end
+  end
+end
+```
+
+### Supported Matchers
+- `eq(expected)`
+- `be(expected)` / `be_nil` / `be_truthy` / `be_falsy`
+- `include(*items)`
+- `raise_error(ExceptionClass, "message")`
+- `respond_to(*methods)`
+
+### Advanced: Execution Context & Extensions
+Regular spec authors do not need to interact with `execution_context` at all—`crspec` automatically isolates `let` memoization, database connections, and stubs invisibly per test.
+
+For gem developers, middleware, or custom test extension authors needing request tracing across child fibers, `execution_context` (or `current_context`) provides an encapsulated, thread-safe store:
+
+```ruby
+before do
+  execution_context[:trace_id] = "TX-12345"
+end
+
+it "reads execution context metadata" do
+  expect(execution_context[:trace_id]).to eq("TX-12345")
+end
+```
+
+---
+
+## Fiber-Isolated Mocking (`crspec-mock`)
+
+`crspec-mock` routes all doubles and stubs through `Fiber[:crspec_mock_space]`, allowing parallel tests to stub methods on shared target objects without cross-test pollution:
+
+```ruby
+Crspec.describe PaymentGateway do
+  let(:stripe_client) { instance_double(Stripe::Charge) }
+
+  it "stubs credit card processing concurrently" do
+    allow(stripe_client).to receive(:create).with(amount: 5000).and_return(status: "succeeded")
+    
+    result = stripe_client.create(amount: 5000)
+    expect(result[:status]).to eq("succeeded")
+  end
+end
+```
+
+---
+
+## Rails Concurrency & Parallel Testing (`crspec-rails`)
+
+### Database Isolation & Connection Leasing
+Wrap examples in connection leasing and transaction savepoints:
+
+```ruby
+Crspec.describe User, type: :model do
+  around do |example|
+    Crspec::Rails::DatabaseIsolation.wrap_example(example)
+  end
+end
+```
+
+### Rails Parallel Testing Setup
+Configure worker counts and setup/teardown hooks:
+
+```ruby
+Crspec::Rails::Parallel.parallelize(workers: 4) do
+  parallelize_setup do |worker_number|
+    # Prepare worker database, seed data, etc.
+    puts "Worker #{worker_number} starting (TEST_ENV_NUMBER=#{ENV['TEST_ENV_NUMBER']})"
+  end
+
+  parallelize_teardown do |worker_number|
+    puts "Worker #{worker_number} tearing down"
+  end
+end
+```
+
+### Multi-Fiber Integration Server
+Boot an embedded multi-threaded/multi-fiber Puma server for system/browser specs:
+
+```ruby
+Crspec::Rails::SystemServer.start_concurrent_server!(Rails.application, 9887)
+```
+
+---
+
+## Migrating from RSpec (`crspec-transpile`)
+
+Use the built-in Prism-powered transpiler CLI to convert legacy RSpec suites to Crspec:
+
+```bash
+# 1. Analyze your test directory for thread-unsafe patterns (e.g. before(:all))
+mise exec -- crspec-transpile --analyze spec/
+
+# 2. Automatically transpile RSpec code to Crspec syntax in-place
+mise exec -- crspec-transpile --write spec/
+```
+
+---
+
+## Running Specs
+
+Execute your test suite concurrently using the `crspec` executable:
+
+```bash
+# Run specs with default concurrency (number of CPU cores)
+mise exec -- crspec spec/
+
+# Run specs with specific concurrency
+mise exec -- crspec -c 8 spec/models/
+```
+
+---
+
+## Development & Testing
+
+To run the internal framework unit tests (built with **Minitest**):
+
+```bash
+mise exec -- bundle exec rake test
+```
+
+---
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE.txt).

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "lib"
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = true
+end
+
+task default: :test

data/demo.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+require "bundler/inline"
+
+gemfile do
+  source "https://rubygems.org"
+  gem "crspec", path: __dir__
+  gem "prism"
+end
+
+require "crspec"
+
+puts "================================================================="
+puts "  Crspec Single-File Inline Demo & Feature Verification          "
+puts "================================================================="
+
+# Reset global state for clean standalone run
+Crspec.reset!
+
+# Domain Models
+class User
+  attr_accessor :name, :email
+
+  def initialize(name:, email:)
+    @name = name
+    @email = email
+  end
+
+  def valid?
+    return false if name.nil? || email.nil?
+
+    email.include?("@")
+  end
+end
+
+class PaymentProcessor
+  def charge(amount)
+    "real_charge_#{amount}"
+  end
+end
+
+# 1. Core DSL, Context Isolation, Lazy Let Memoization, Matchers
+Crspec.describe User, type: :model do
+  let(:valid_attributes) { { name: "Jane Doe", email: "jane@example.com" } }
+  subject(:user) { User.new(**valid_attributes) }
+
+  before do
+    # Per-example setup hook
+  end
+
+  it "validates primary attributes concurrently" do
+    expect(user.valid?).to be(true)
+    expect(user.name).to eq("Jane Doe")
+    expect(user.email).to include("example.com")
+  end
+
+  context "when email is invalid" do
+    let(:valid_attributes) { { name: "Jane Doe", email: nil } }
+
+    it "flags validation errors" do
+      expect(user.valid?).to eq(false)
+    end
+  end
+
+  context "when error is expected" do
+    it "catches raised exceptions" do
+      expect { raise ArgumentError, "Invalid user input" }.to raise_error(ArgumentError, "Invalid user input")
+    end
+  end
+end
+
+# 2. Fiber-Aware Mocking Engine (crspec-mock)
+Crspec.describe PaymentProcessor do
+  let(:processor) { PaymentProcessor.new }
+
+  it "supports fiber-isolated method stubs" do
+    allow(processor).to receive(:charge).with(5000).and_return("succeeded")
+    expect(processor.charge(5000)).to eq("succeeded")
+  end
+
+  it "supports test doubles and method expectations" do
+    gateway_double = double("StripeGateway", process: "ok")
+    expect(gateway_double.process).to eq("ok")
+  end
+end
+
+# 3. Rails Parallel Worker Integration (crspec-rails)
+Crspec::Rails::Parallel.parallelize(workers: 4) do
+  parallelize_setup do |worker_num|
+    # Per-worker setup hook (e.g. database setup for worker_num)
+  end
+
+  parallelize_teardown do |worker_num|
+    # Per-worker teardown hook
+  end
+end
+
+# 4. Prism AST Transpiler Verification (crspec-transpiler)
+rspec_sample_code = <<~RUBY
+  RSpec.describe "Legacy Suite" do
+    it "runs" do
+      expect(1).to eq(1)
+    end
+  end
+RUBY
+
+transpiled = Crspec::Transpiler::Rewriter.new(rspec_sample_code).transpile
+puts "[Prism Transpiler Check] RSpec -> Crspec: #{transpiled.include?("Crspec.describe") ? "PASSED" : "FAILED"}"
+
+# 5. Concurrent Multi-Threaded Execution Kernel
+puts "\n[Executing Specs Concurrently Across 4 Worker Threads]..."
+runner = Crspec::Runner.new(concurrency: 4)
+runner.run(Crspec.world.example_groups)
+
+puts "\n---------------- Execution Summary ----------------"
+puts "Total Duration : #{runner.total_duration.round(4)}s"
+puts "Passed Examples: #{runner.passed_examples.size}"
+puts "Failed Examples: #{runner.failed_examples.size}"
+puts "---------------------------------------------------"
+
+if runner.success?
+  puts "\nSUCCESS: All specs executed concurrently across 4 worker threads and passed cleanly!"
+else
+  puts "\nFAILURE: Some specs failed."
+  exit 1
+end

data/exe/crspec

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "crspec"
+require "crspec/cli"
+
+success = Crspec::CLI.run(ARGV)
+exit(success ? 0 : 1)

data/exe/crspec-transpile

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift File.expand_path("../lib", __dir__)
+require "crspec"
+require "crspec/transpiler/cli"
+
+Crspec::Transpiler::CLI.run(ARGV)

data/lib/crspec/cli.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../crspec"
+
+module Crspec
+  class CLI
+    def self.run(args)
+      new(args).run
+    end
+
+    def initialize(args)
+      @args = args
+      @concurrency = Etc.nprocessors
+      @paths = []
+    end
+
+    def run
+      parse_options
+      load_specs
+      runner = Runner.new(concurrency: @concurrency)
+      groups = Crspec.world.example_groups
+
+      if groups.empty?
+        puts "No example groups found."
+        return true
+      end
+
+      puts "Running Crspec suite with concurrency #{@concurrency}..."
+      runner.run(groups)
+
+      puts "\nFinished in #{runner.total_duration.round(4)} seconds"
+      puts "#{runner.passed_examples.size + runner.failed_examples.size} examples, #{runner.failed_examples.size} failures"
+
+      unless runner.failed_examples.empty?
+        puts "\nFailures:"
+        runner.failed_examples.each_with_index do |ex, idx|
+          puts "#{idx + 1}) #{ex.description}"
+          puts "   Failure/Error: #{ex.error.message}"
+          puts "   #{ex.error.backtrace&.first}" if ex.error.backtrace
+        end
+      end
+
+      runner.success?
+    end
+
+    private
+
+    def parse_options
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: crspec [options] [files or directories]"
+
+        opts.on("-c", "--concurrency N", Integer, "Number of concurrent worker threads") do |n|
+          @concurrency = n
+        end
+
+        opts.on("-h", "--help", "Show help") do
+          puts opts
+          exit 0
+        end
+      end
+
+      @paths = parser.parse(@args)
+      @paths = ["spec"] if @paths.empty?
+    end
+
+    def load_specs
+      files = []
+      @paths.each do |p|
+        if File.directory?(p)
+          files.concat(Dir.glob(File.join(p, "**", "*_spec.rb")))
+        elsif File.file?(p)
+          files << p
+        end
+      end
+
+      files.uniq.each do |file|
+        require File.expand_path(file)
+      end
+    end
+  end
+end

data/lib/crspec/dsl.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "example_group"
+
+module Crspec
+  class World
+    def self.instance
+      @instance ||= new
+    end
+
+    def self.reset!
+      @instance = new
+    end
+
+    attr_reader :example_groups
+
+    def initialize
+      @example_groups = []
+    end
+
+    def register(group)
+      @example_groups << group
+    end
+  end
+
+  def self.describe(description, metadata = {}, &block)
+    group = ExampleGroup.define(description, metadata, nil, &block)
+    World.instance.register(group)
+    group
+  end
+
+  def self.world
+    World.instance
+  end
+
+  def self.reset!
+    World.reset!
+  end
+end

data/lib/crspec/example.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Crspec
+  class Example
+    attr_reader :id, :description, :metadata, :example_group, :block, :status, :error, :execution_time
+
+    def initialize(description, metadata, example_group, block)
+      @id = SecureRandom.uuid
+      @description = description
+      @metadata = metadata.freeze
+      @example_group = example_group
+      @block = block
+      @status = :pending
+      @error = nil
+      @execution_time = 0
+    end
+
+    def execute!
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      instance = @example_group.create_instance(self)
+
+      begin
+        run_hooks(instance, :before)
+        instance.instance_exec(&@block) if @block
+        @status = :passed
+      rescue StandardError, ExpectationNotMetError => e
+        @status = :failed
+        @error = e
+      ensure
+        begin
+          run_hooks(instance, :after)
+        rescue StandardError => e
+          if @status == :passed
+            @status = :failed
+            @error = e
+          end
+        end
+        @execution_time = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+      end
+    end
+
+    private
+
+    def run_hooks(instance, type)
+      hooks = @example_group.ancestor_hooks(type)
+      hooks.each do |hook|
+        instance.instance_exec(&hook)
+      end
+    end
+  end
+end

data/lib/crspec/example_group.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+require_relative "expectations"
+require_relative "example"
+require_relative "mock/double"
+
+module Crspec
+  class ExampleGroup
+    include Expectations
+    include Mock::DSL
+
+    attr_reader :description, :metadata, :parent, :examples, :children, :before_hooks, :after_hooks
+
+    def initialize(description, metadata = {}, parent = nil)
+      @description = description
+      @metadata = metadata.freeze
+      @parent = parent
+      @examples = []
+      @children = []
+      @before_hooks = []
+      @after_hooks = []
+      @let_blocks = {}
+      @eager_lets = []
+    end
+
+    def self.define(description, metadata = {}, parent = nil, &block)
+      group = new(description, metadata, parent)
+      group.instance_eval(&block) if block
+      group
+    end
+
+    def describe(description, metadata = {}, &block)
+      child = self.class.define(description, metadata, self, &block)
+      @children << child
+      child
+    end
+    alias context describe
+
+    def it(description = nil, metadata = {}, &block)
+      example = Example.new(description || "unnamed example", metadata, self, block)
+      @examples << example
+      example
+    end
+    alias specify it
+
+    def let(name, &block)
+      @let_blocks[name.to_sym] = block
+    end
+
+    def let!(name, &block)
+      let(name, &block)
+      @eager_lets << name.to_sym
+    end
+
+    def subject(name = nil, &block)
+      if name
+        let(name, &block)
+        let(:subject) { send(name) }
+      else
+        let(:subject, &block)
+      end
+    end
+
+    def before(_scope = :each, &block)
+      @before_hooks << block
+    end
+
+    def after(_scope = :each, &block)
+      @after_hooks.unshift(block)
+    end
+
+    def ancestor_hooks(type)
+      hooks = []
+      curr = self
+      ancestors = []
+      while curr
+        ancestors.unshift(curr)
+        curr = curr.parent
+      end
+
+      ancestors.each do |grp|
+        list = type == :before ? grp.before_hooks : grp.after_hooks
+        hooks.concat(list)
+      end
+      hooks
+    end
+
+    def ancestor_let_blocks
+      blocks = {}
+      curr = self
+      ancestors = []
+      while curr
+        ancestors.unshift(curr)
+        curr = curr.parent
+      end
+      ancestors.each do |grp|
+        blocks.merge!(grp.instance_variable_get(:@let_blocks))
+      end
+      blocks
+    end
+
+    def ancestor_eager_lets
+      eager = []
+      curr = self
+      while curr
+        eager.concat(curr.instance_variable_get(:@eager_lets))
+        curr = curr.parent
+      end
+      eager
+    end
+
+    def create_instance(example)
+      klass = Class.new do
+        include Expectations
+        include Mock::DSL
+
+        attr_reader :__crspec_example__
+
+        def initialize(example)
+          @__crspec_example__ = example
+        end
+
+        def execution_context
+          ExecutionContext.current
+        end
+        alias current_context execution_context
+
+        def described_class
+          nil
+        end
+      end
+
+      lets = ancestor_let_blocks
+      lets.each do |let_name, let_proc|
+        current_proc = let_proc
+        klass.define_method(let_name) do
+          ExecutionContext.current.fetch_memoized(let_name) do
+            instance_exec(&current_proc)
+          end
+        end
+      end
+
+      inst = klass.new(example)
+
+      # Evaluate eager lets
+      eager_lets = ancestor_eager_lets
+      eager_lets.each do |name|
+        inst.send(name)
+      end
+
+      inst
+    end
+  end
+end