riteway 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 6761c022b9dd95c5940eb0d3b373306d29aec20ef8b1b952bbe56e13f148fdaf
+  data.tar.gz: 4583be719e30bfaaa0d2174e727b07c647125681c552e032eb26beffda272670
+SHA512:
+  metadata.gz: efc1d4c26e6c2bb6660543b6106bc6853db6e4508ade85ea1a9ff3eaa25eb79771e314dcbcacde64971caaf5a131c5d1d6d26f7bf83bf0a1a9b5827c32ad9341
+  data.tar.gz: 7ad168dea1489678eebbb73fdef53ae15a1777f8e835ac816100045fa6dacf10407aebf6e00eb96b1fbb795e876d85b8c547593d5ea3bcbd009a3961ac89ff28

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-11
+
+### Added
+
+- `Riteway.assert` with RSpec and Minitest adapters
+- `Riteway.attempt` for testing error cases
+- `Riteway.count_keys` convenience helper
+- `Riteway.match` curried text search
+
+[unreleased]: https://github.com/mycargus/riteway-ruby/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/mycargus/riteway-ruby/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Hargiss
+
+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,275 @@
+# Riteway Ruby
+
+[![CI](https://github.com/mycargus/riteway-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/mycargus/riteway-ruby/actions/workflows/ci.yml)
+
+**The standard testing assertion style for AI Driven Development (AIDD) and software agents.**
+
+This is the Ruby port of the [riteway JavaScript library](https://github.com/paralleldrive/riteway).
+
+Riteway is a testing assertion style and philosophy which leads to simple, readable, helpful unit tests for humans and AI agents.
+
+It lets you write better, more readable tests with a fraction of the code that traditional assertion frameworks would use.
+
+Riteway is the AI-native way to build a modern test suite. It pairs well with RSpec, Claude Code, Cursor Agent, and more.
+
+* **R**eadable
+* **I**solated/**I**ntegrated
+* **T**horough
+* **E**xplicit
+
+Riteway forces you to write **R**eadable, **I**solated, and **E**xplicit tests, because that's the only way you can use the API. It also makes it easier to be thorough by making test assertions so simple that you'll want to write more of them.
+
+## Why Riteway for AI Driven Development?
+
+Riteway's structured approach makes it ideal for AIDD:
+
+**📖 Learn more:** [Better AI Driven Development with Test Driven Development](https://medium.com/effortless-programming/better-ai-driven-development-with-test-driven-development-d4849f67e339)
+
+- **Clear requirements**: The given/should structure and 5-question framework help AI better understand exactly what to build
+- **Readable by design**: Natural language descriptions make tests comprehensible to both humans and AI
+- **Simple API**: Minimal surface area reduces AI confusion and hallucinations
+- **Token efficient**: Concise syntax saves valuable context window space
+
+## The 5 Questions Every Test Must Answer
+
+There are [5 questions every unit test must answer](https://medium.com/javascript-scene/what-every-unit-test-needs-f6cd34d9836d). Riteway forces you to answer them.
+
+1. What is the unit under test (module, function, class, whatever)?
+2. What should it do? (Prose description)
+3. What was the actual output?
+4. What was the expected output?
+5. How do you reproduce the failure?
+
+## Installing
+
+Add to your `Gemfile`:
+
+```ruby
+gem "riteway"
+```
+
+Or install directly:
+
+```shell
+gem install riteway
+```
+
+Then require the adapter for your test framework. Use one or the other — not both.
+
+**RSpec** — require in `spec/spec_helper.rb`:
+
+```ruby
+require "riteway/rspec"
+```
+
+Optional: filter Riteway internals from RSpec backtraces so failures point directly to your test code:
+
+```ruby
+RSpec.configure do |config|
+  config.backtrace_exclusion_patterns << /lib\/riteway/
+end
+```
+
+**Minitest** — require in `test/test_helper.rb`:
+
+```ruby
+require "minitest/autorun"
+require "riteway/minitest"
+```
+
+Minitest ships with Ruby's standard library — no extra gem needed.
+
+## Example Usage
+
+```ruby
+require "riteway/rspec"
+
+# A function to test
+def sum(*args)
+  args.each { |n| raise TypeError, "Not a number: #{n.inspect}" unless n.is_a?(Numeric) }
+  args.reduce(0, :+)
+end
+
+RSpec.describe "sum()" do
+  it "given no arguments, should return 0" do
+    Riteway.assert(
+      given: "no arguments",
+      should: "return 0",
+      actual: sum(),
+      expected: 0
+    )
+  end
+
+  it "given zero, should return the correct sum" do
+    Riteway.assert(
+      given: "zero",
+      should: "return the correct sum",
+      actual: sum(2, 0),
+      expected: 2
+    )
+  end
+
+  it "given negative numbers, should return the correct sum" do
+    Riteway.assert(
+      given: "negative numbers",
+      should: "return the correct sum",
+      actual: sum(1, -4),
+      expected: -3
+    )
+  end
+
+  it "given a non-numeric argument, should raise TypeError" do
+    error = Riteway.attempt(method(:sum), 1, "NaN")
+
+    Riteway.assert(
+      given: "a non-numeric argument",
+      should: "raise TypeError",
+      actual: error.class,
+      expected: TypeError
+    )
+  end
+end
+```
+
+## Output
+
+Riteway uses your test framework's output. The failure message always includes the given/should context; the diff format varies slightly between RSpec (colorized diff) and Minitest (simple expected/got lines).
+
+For RSpec, use `--format documentation` for full prose output:
+
+```shell
+bundle exec rspec --format documentation
+```
+
+```
+sum()
+  given no arguments, should return 0
+  given zero, should return the correct sum
+  given negative numbers, should return the correct sum
+  given a non-numeric argument, should raise TypeError
+
+Finished in 0.00112 seconds
+4 examples, 0 failures
+```
+
+When a test fails, the given/should context is always included in the error:
+
+```
+Given negative numbers: should return the correct sum
+  expected: -3
+       got: 0
+```
+
+## API
+
+### `Riteway.assert`
+
+```ruby
+Riteway.assert(given:, should:, actual:, expected:) => void, raises
+```
+
+The core assertion. Takes keyword arguments and compares `actual` to `expected` using deep equality (`eq`). All four arguments are required — missing any raises Ruby's native `ArgumentError`.
+
+`assert` uses RSpec's `eq` matcher, which handles deep comparison of arrays, hashes, and nested structures.
+
+```ruby
+Riteway.assert(
+  given: "an array of numbers",
+  should: "equal the expected array",
+  actual: [1, 2, 3].map { |n| n * 2 },
+  expected: [2, 4, 6]
+)
+```
+
+### `Riteway.attempt`
+
+```ruby
+Riteway.attempt(callable = nil, *args, **kwargs, &block) => Error | Any
+```
+
+Execute a callable or block with the given arguments. Returns the error if one is raised, otherwise returns the result. Designed for testing error cases in your assertions. Supports positional args, keyword args, lambdas, procs, and blocks.
+
+`attempt` catches `StandardError` and its subclasses only. Exceptions outside this hierarchy — `SystemExit`, `Interrupt`, `SignalException` — propagate normally. Note that RSpec's `ExpectationNotMetError` inherits from `Exception` (not `StandardError`), so it propagates through `attempt` rather than being caught and returned.
+
+```ruby
+# Block form (most concise)
+error = Riteway.attempt { Integer("not a number") }
+
+# Lambda form
+error = Riteway.attempt(-> { Integer("not a number") })
+
+# Method reference with positional args
+error = Riteway.attempt(method(:sum), 1, "NaN")
+
+# Method reference with keyword args
+result = Riteway.attempt(method(:create_user), name: "Alice", age: 30)
+
+Riteway.assert(
+  given: "a non-numeric string",
+  should: "raise ArgumentError",
+  actual: error.class,
+  expected: ArgumentError
+)
+```
+
+### `Riteway.count_keys`
+
+```ruby
+Riteway.count_keys(hash = {}) => Integer
+```
+
+Given a hash, return a count of its keys. Defaults to `{}` (returns `0`) when called with no arguments. A convenience wrapper for `hash.keys.length` that reads naturally inside a `Riteway.assert` call. Handy when you're adding new state to a hash keyed by ID and want to ensure the correct number of keys were added.
+
+```ruby
+Riteway.assert(
+  given: "a hash with 3 keys",
+  should: "return 3",
+  actual: Riteway.count_keys({ a: 1, b: 2, c: 3 }),
+  expected: 3
+)
+```
+
+### `Riteway.match`
+
+```ruby
+Riteway.match(text) => ->(pattern) => String
+```
+
+Take some text to search and return a lambda which takes a pattern and returns the matched text, or `nil` if no match — consistent with Ruby's own `String#match`. The pattern can be a String or Regexp. String patterns are auto-escaped so regex meta-characters are treated as literals.
+
+```ruby
+contains = Riteway.match("<h1>Dialog Title</h1>")
+
+Riteway.assert(
+  given: "some text and a string pattern",
+  should: "return the matched text",
+  actual: contains.call("Dialog Title"),
+  expected: "Dialog Title"
+)
+
+Riteway.assert(
+  given: "some text and a regex pattern",
+  should: "return the matched text",
+  actual: contains.call(/\w+/),
+  expected: "Dialog"
+)
+
+Riteway.assert(
+  given: "a pattern that does not match",
+  should: "return nil",
+  actual: contains.call("not found"),
+  expected: nil
+)
+```
+
+You can also use `contains.("pattern")` or `contains["pattern"]` as shorthand for `.call`.
+
+## Publishing
+
+See [RELEASING.md](RELEASING.md) for the full release process.
+
+`rake release` is intentionally disabled to prevent automated publishing.
+
+## License
+
+MIT

data/lib/riteway/match.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Riteway
+  # Returns a lambda that searches text for a pattern (String or Regexp).
+  # Returns the matched text on success, or nil if no match — consistent with
+  # Ruby's String#match which also returns nil on no match.
+  def self.match(text)
+    raise TypeError, "match expects a String, got #{text.class}" unless text.is_a?(String)
+
+    ->(pattern) {
+      unless pattern.is_a?(String) || pattern.is_a?(Regexp)
+        raise TypeError,
+              "pattern must be a String or Regexp, got #{pattern.class}"
+      end
+      raise ArgumentError, "pattern must not be empty" if pattern.is_a?(String) && pattern.empty?
+
+      re = pattern.is_a?(String) ? Regexp.new(Regexp.escape(pattern)) : pattern
+      matched = text.match(re)
+      matched ? matched[0] : nil
+    }
+  end
+end

data/lib/riteway/minitest.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "minitest"
+require "riteway"
+
+module Riteway
+  if defined?(ADAPTER)
+    raise LoadError,
+          "riteway: adapter conflict — #{ADAPTER} already loaded. " \
+          "Only require one adapter (riteway/rspec or riteway/minitest)."
+  end
+
+  ADAPTER = :minitest
+
+  module MinitestLifecycle
+    def before_setup
+      super
+      Thread.current[:riteway_minitest_context] = self
+    end
+
+    def after_teardown
+      Thread.current[:riteway_minitest_context] = nil
+      super
+    end
+  end
+
+  def self.assert(given:, should:, actual:, expected:)
+    ctx = Thread.current[:riteway_minitest_context]
+    unless ctx
+      raise "Riteway.assert must be called inside an it/test block. " \
+            "Ensure `require \"riteway/minitest\"` is in your test_helper.rb " \
+            "and that assert is only called from within a test context."
+    end
+    unless given.is_a?(String) && !given.empty?
+      raise ArgumentError,
+            "given: must be a non-empty String, got #{given.inspect}"
+    end
+    unless should.is_a?(String) && !should.empty?
+      raise ArgumentError,
+            "should: must be a non-empty String, got #{should.inspect}"
+    end
+
+    message = "Given #{given}: should #{should}"
+    expected.nil? ? ctx.assert_nil(actual, message) : ctx.assert_equal(expected, actual, message)
+    nil
+  end
+end
+
+Minitest::Test.include Riteway::MinitestLifecycle

data/lib/riteway/rspec.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+begin
+  require "rspec/expectations"
+  require "rspec/matchers"
+rescue LoadError
+  raise LoadError,
+        "riteway/rspec requires the 'rspec' gem. Add `gem \"rspec\"` to your Gemfile, " \
+        "or use `require \"riteway/minitest\"` for Minitest."
+end
+require "riteway"
+
+module Riteway
+  if defined?(ADAPTER)
+    raise LoadError,
+          "riteway: adapter conflict — #{ADAPTER} already loaded. " \
+          "Only require one adapter (riteway/rspec or riteway/minitest)."
+  end
+
+  ADAPTER = :rspec
+
+  # Internal — not part of the public API. Isolates RSpec matcher methods
+  # so they don't pollute Riteway's module namespace.
+  module RSpecBridge
+    extend RSpec::Matchers
+  end
+
+  def self.assert(given:, should:, actual:, expected:)
+    unless RSpec.respond_to?(:current_example) && RSpec.current_example
+      raise "Riteway.assert must be called inside an it/specify block, not at describe-level. " \
+            "Move this assertion inside an `it` block."
+    end
+    unless given.is_a?(String) && !given.empty?
+      raise ArgumentError,
+            "given: must be a non-empty String, got #{given.inspect}"
+    end
+    unless should.is_a?(String) && !should.empty?
+      raise ArgumentError,
+            "should: must be a non-empty String, got #{should.inspect}"
+    end
+
+    matcher = RSpecBridge.eq(expected)
+    return if matcher.matches?(actual)
+
+    raise RSpec::Expectations::ExpectationNotMetError,
+          "Given #{given}: should #{should}\n#{matcher.failure_message}"
+  end
+end

data/lib/riteway/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Riteway
+  VERSION = "0.1.0"
+end

data/lib/riteway.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require_relative "riteway/version"
+require_relative "riteway/match"
+
+module Riteway
+  def self.assert(**)
+    raise "Riteway.assert requires an adapter. " \
+          "Add `require \"riteway/rspec\"` or `require \"riteway/minitest\"` to your test helper."
+  end
+
+  # Calls callable (or block) with given args. Returns the error if raised,
+  # otherwise returns the result. Catches StandardError and subclasses only —
+  # SystemExit, Interrupt, SignalException, etc. propagate normally.
+  def self.attempt(callable = nil, *args, **kwargs, &block)
+    raise ArgumentError, "attempt accepts a callable or a block, not both" if callable && block
+
+    fn = callable || block
+    raise ArgumentError, "attempt requires a callable or a block" unless fn
+    raise ArgumentError, "attempt expects a callable (responds to #call), got #{fn.class}" unless fn.respond_to?(:call)
+
+    begin
+      kwargs.empty? ? fn.call(*args) : fn.call(*args, **kwargs)
+    rescue => error
+      error
+    end
+  end
+
+  def self.count_keys(hash = {})
+    raise TypeError, "count_keys expects a Hash, got #{hash.class}" unless hash.is_a?(Hash)
+
+    hash.keys.length
+  end
+end

metadata

@@ -0,0 +1,121 @@
+--- !ruby/object:Gem::Specification
+name: riteway
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michael Hargiss
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rspec-expectations
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: Ruby port of the riteway JavaScript testing library.
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/riteway.rb
+- lib/riteway/match.rb
+- lib/riteway/minitest.rb
+- lib/riteway/rspec.rb
+- lib/riteway/version.rb
+homepage: https://github.com/mycargus/riteway-ruby
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/mycargus/riteway-ruby
+  source_code_uri: https://github.com/mycargus/riteway-ruby
+  changelog_uri: https://github.com/mycargus/riteway-ruby/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/mycargus/riteway-ruby/issues
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Unit tests that always supply a good bug report when they fail.
+test_files: []