riptide 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml ADDED
@@ -0,0 +1,7 @@
1
+ ---
2
+ SHA256:
3
+ metadata.gz: ba0fc3b9bed3ed751407638932d2837116cf6e22e60fb0af48a1264d48436ab8
4
+ data.tar.gz: fedcb8f7af65998fd82f9310f7b0cd9bf59f6e9c462d775ee871c537397b28bb
5
+ SHA512:
6
+ metadata.gz: 1d3e6be891fba1e4a1d1a93f975af5adc8ad26d409288141d866bdd7d3ac0a18ed026c254869f826339582f9aef3b220cac121373ba4906b3ef4ed27b88c8e0b
7
+ data.tar.gz: 7c52dda70342567a5b89c58f1b1819ad0303b0a2883d226958744f89dc829a3c7ea2ea80b08cceb523f3f390d3648d5905ea016152873c586e9a2be6ca6869b7
data/CHANGELOG.md ADDED
@@ -0,0 +1,8 @@
1
+ # Changelog
2
+
3
+ ## 0.1.0 (2026-11-18)
4
+
5
+
6
+ ### Features
7
+
8
+ * publish riptide to RubyGems ([41916c0](https://github.com/nallenscott/riptide/commit/41916c089f1769101ffe2d30ccacfa736d370247))
data/LICENSE.txt ADDED
@@ -0,0 +1,21 @@
1
+ The MIT License (MIT)
2
+
3
+ Copyright (c) 2026 Nathan Allen
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in
13
+ all copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
21
+ THE SOFTWARE.
data/README.md ADDED
@@ -0,0 +1,157 @@
1
+ # riptide
2
+
3
+ **Run the tests your changes can affect.**
4
+
5
+ Riptide is a test impact analysis engine for Rails and Minitest. It records what each test depends on at runtime, then uses that history to determine which tests need to run when the code changes.
6
+
7
+ It understands Ruby methods, constants, class loading, ActiveRecord, database queries, fixtures, and file access. It also tracks the code and files loaded during application and test setup.
8
+
9
+ Test history lives in Git and can be reused across pull requests, main, and release branches, regardless of how changes were merged. No external services or changes to your tests required.
10
+
11
+ ![A full run of 291 tests, then a one-line change to Order#total_cents that runs only the 20 tests that use it](docs/assets/riptide-demo.gif)
12
+
13
+ ## Why Riptide?
14
+
15
+ Large Rails applications can spend a lot of CI time running tests that have nothing to do with the changes being tested.
16
+
17
+ Selecting tests by filename only gets you so far. Ruby's dynamic behavior makes it difficult to know what a test actually depends on without running it.
18
+
19
+ Riptide records those dependencies as tests execute. When something changes, it compares the changed code with what each test previously used.
20
+
21
+ The result is a smaller test run, with an explanation of why each test was selected.
22
+
23
+ ## How it works
24
+
25
+ Riptide builds a dependency history from passing test runs. Each run records the exact versions of the files and code it used.
26
+
27
+ When those files change, Riptide analyzes the differences and determines which recorded runs are still valid.
28
+
29
+ For example, consider three tests:
30
+
31
+ - `test_widget` calls `Widget#size`.
32
+ - `test_other` calls `Other#size`.
33
+ - `test_both` calls both methods.
34
+
35
+ Changing the implementation of `Widget#size` selects `test_widget` and `test_both`. The recorded run for `test_other` is still valid.
36
+
37
+ This example comes from Riptide's own end-to-end tests, which also verify that passing runs can be reused after pull requests are merged, including squash merges.
38
+
39
+ ### What Riptide tracks
40
+
41
+ Riptide records dependencies on executed methods and blocks, constants, classes, database tables, fixtures, files, and directories. It also accounts for code executed during application boot, test setup, and class loading.
42
+
43
+ Source changes are analyzed with Prism. Changes to unrelated methods, comments, or whitespace don't automatically invalidate every test associated with a file.
44
+
45
+ ### Test history across branches
46
+
47
+ Each passing run records the versions of its dependencies. Riptide checks those versions against the current files, rather than calculating changes from a Git diff base.
48
+
49
+ A run recorded on one branch can still be valid on another.
50
+
51
+ Records are stored in Git refs under `refs/riptide/`. Builds fetch the history they need and publish new results when they finish.
52
+
53
+ ## Getting started
54
+
55
+ Riptide currently supports Ruby 4.0, Minitest 5.26.1 or later (below 7), and Git 2.45 or later.
56
+
57
+ Add it to your Gemfile:
58
+
59
+ ```ruby
60
+ group :test do
61
+ gem "riptide", git: "https://github.com/nallenscott/riptide"
62
+ end
63
+ ```
64
+
65
+ Configure Riptide at the beginning of `test_helper.rb`, before Rails loads:
66
+
67
+ ```ruby
68
+ require "riptide"
69
+
70
+ Riptide.configure do |c|
71
+ c.suite = "unit"
72
+ c.mode = :dry_run
73
+ end
74
+
75
+ require_relative "../config/environment"
76
+ require "rails/test_help"
77
+ require "minitest/riptide_plugin"
78
+ ```
79
+
80
+ Run your tests normally:
81
+
82
+ ```bash
83
+ bundle exec rails test
84
+ ```
85
+
86
+ Riptide supports three modes:
87
+
88
+ | Mode | Behavior |
89
+ |---|---|
90
+ | `:record` | Runs the full suite and records dependencies. |
91
+ | `:dry_run` | Runs the full suite and reports which tests would have been selected. |
92
+ | `:enforce` | Runs only the selected tests. |
93
+
94
+ Start with `:dry_run` to check selection decisions against your existing suite.
95
+
96
+ ## CI integration
97
+
98
+ Riptide shares test history between CI builds using Git refs.
99
+
100
+ For a pull request:
101
+
102
+ ```bash
103
+ bundle exec riptide fetch --pr 42 --target main
104
+ bundle exec rails test
105
+ bundle exec riptide publish --suite unit --pr 42 --target main
106
+ ```
107
+
108
+ On main:
109
+
110
+ ```bash
111
+ bundle exec riptide fetch --branch main --harvest
112
+ bundle exec rails test
113
+ bundle exec riptide publish --suite unit --branch main --harvest
114
+ ```
115
+
116
+ Riptide can identify which pull requests have landed, reuse their passing runs, and remove records that are no longer needed.
117
+
118
+ See the [CI guide](docs/ci.md) for release branches, parallel test processes, and configuration options.
119
+
120
+ ## Auditing your test suite
121
+
122
+ Riptide also uses recorded test execution to find tests that may be worth removing or restructuring.
123
+
124
+ ```bash
125
+ bundle exec riptide fetch --branch main
126
+ bundle exec riptide audit --suite unit
127
+ ```
128
+
129
+ The audit reports inherited tests, potential duplicates, tests that perform no assertions or mock expectations, and large tests that may benefit from being split up.
130
+
131
+ It uses recorded execution, assertions, and statement-level dependencies to support its findings. The command is read-only and doesn't modify your tests.
132
+
133
+ ## Status and limitations
134
+
135
+ Riptide is under active development and is being validated against a large Rails application's CI.
136
+
137
+ Test selection is conservative when there's insufficient history or a previous test failure. Tests with no recorded run are executed, and failures continue running until a later build passes them.
138
+
139
+ Some dependencies cannot be observed reliably, including external services, time-dependent behavior, and code executed in child processes. These may require additional fallback configuration.
140
+
141
+ Review the [limitations](docs/limitations.md) before enabling `:enforce` in CI.
142
+
143
+ ## Documentation
144
+
145
+ - [Architecture and dependency tracking](docs/architecture.md)
146
+ - [CI integration and Git storage](docs/ci.md)
147
+ - [Configuration reference](docs/configuration.md)
148
+ - [Test auditing](docs/auditing.md)
149
+ - [Limitations and fallback behavior](docs/limitations.md)
150
+
151
+ ## Development
152
+
153
+ Run `bin/setup` to install dependencies, then `rake test`.
154
+
155
+ ## License
156
+
157
+ MIT. See [LICENSE.txt](LICENSE.txt).
data/exe/riptide ADDED
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ require "riptide/cli"
5
+
6
+ exit Riptide::CLI.new(ARGV).call
@@ -0,0 +1,49 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "mkmf"
4
+ require_relative "ruby_source"
5
+ require_relative "../../lib/riptide/version"
6
+
7
+ # Without the headers the tracer needs, or on a Ruby that doesn't have
8
+ # everything it calls, the gem still installs and riptide stays off.
9
+ #
10
+ # RIPTIDE_TRACER=on builds the tracer on a Ruby it isn't written for yet, to
11
+ # see whether it works there, and RIPTIDE_TRACER=off builds without it.
12
+
13
+ # The errors from mkmf's last check, which only its log keeps. The compiler's
14
+ # output sits between the command and the program it checked, warnings and
15
+ # all, so this keeps the lines that say what failed.
16
+ def compiler_errors
17
+ lines = File.exist?("mkmf.log") ? File.readlines("mkmf.log") : []
18
+ checked = lines.rindex("checked program was:\n") or return []
19
+ command = lines[0...checked].rindex { |line| line.rstrip.end_with?('"') } || -1
20
+ lines[(command + 1)...checked].grep(/error|undefined|Undefined|referenced from|\A\s+"/).first(20)
21
+ end
22
+
23
+ off = nil
24
+ begin
25
+ raise "riptide only traces CRuby" unless RUBY_ENGINE == "ruby"
26
+ raise "RIPTIDE_TRACER is off" if ENV["RIPTIDE_TRACER"] == "off"
27
+
28
+ minor = RUBY_VERSION[/\A\d+\.\d+/]
29
+ raise "riptide's tracer isn't written for Ruby #{minor} yet" unless ENV["RIPTIDE_TRACER"] == "on" || Riptide::TRACED_RUBIES.include?(minor)
30
+
31
+ RubySource.include_dirs.each { |dir| $INCFLAGS << " -I#{dir}" }
32
+ $CFLAGS << " -Wno-unused-function -Wno-unused-parameter"
33
+ # A struct that moved in a patch release, or a function this Ruby doesn't
34
+ # export, turns riptide off, not the install. Only linking catches the
35
+ # second, since the extension loads fine and dies when the tracer calls it.
36
+ source = File.read(File.join(__dir__, "riptide_native.c")).sub(%(#include "riptide_build.h"\n), "")
37
+ unless try_link(source + MAIN_DOES_NOTHING)
38
+ errors = compiler_errors
39
+ warn "riptide's tracer didn't compile:\n#{errors.join}" if errors.any?
40
+ raise "the tracer doesn't build against Ruby #{RUBY_VERSION}"
41
+ end
42
+ rescue StandardError => e
43
+ off = e.message
44
+ warn "riptide will stay off: #{off}"
45
+ end
46
+
47
+ # Why the tracer isn't built, when it isn't.
48
+ File.write("riptide_build.h", off ? "#define RIPTIDE_UNSUPPORTED #{off.dump}\n" : "")
49
+ create_makefile("riptide/riptide_native")