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.
@@ -0,0 +1,446 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "json"
4
+ require "digest"
5
+ require "fileutils"
6
+ require "securerandom"
7
+ require "set"
8
+
9
+ module Riptide
10
+ # Recorded runs and open failures, kept in git. A unit is one suite's
11
+ # record for one build: a branch, keyed branches/<branch>, or a PR, keyed
12
+ # prs/<number>. It's two refs, written and deleted together:
13
+ #
14
+ # refs/riptide/runs/<suite>/<key> a tag wrapping the Index's tree
15
+ # refs/riptide/stamps/<suite>/<key> a tag wrapping a small tree:
16
+ # format the index's format
17
+ # runs the runs tag it pairs with
18
+ # marks/<ab> per test, its open failures' ids
19
+ # landing/target for a PR, the branch it merges into
20
+ # landing/base/..., landing/tested/... the paths it changed, at the
21
+ # merge base and as tested
22
+ #
23
+ # The refs point at tags, not commits, so a push uploads only the objects
24
+ # the host doesn't already have. The stamp lets a build read every PR's
25
+ # open failures and landing record without downloading its runs, and its
26
+ # date is when the unit was last written.
27
+ #
28
+ # `Store.fetch` leaves exactly the units a build reads as local refs, so
29
+ # test processes read every local unit of their suite from a read-only
30
+ # .git and append to their own log. #publish folds the logs into the
31
+ # build's unit and pushes it.
32
+ class Store
33
+ # A test process's outcome for a test. +sets+ and +inputs+ are nil when
34
+ # riptide couldn't trace what the test ran. +file+ is where the test is
35
+ # defined. +body+ is its statements, as [line, set id, ms, compared,
36
+ # wrote, reads] with the set's id in the log, +ms+ how long the test
37
+ # took, +body_line+ the line its method or block starts on, +body_file+
38
+ # where the body is defined when that isn't +file+, and +inherited_from+
39
+ # the test class whose test it is when the test's class only inherits it.
40
+ Run = Struct.new(:test, :at, :passed, :sets, :inputs, :file, :body, :ms, :body_line, :body_file, :inherited_from, keyword_init: true)
41
+
42
+ # Who a build is. +key+ names its unit, +upstream+ the branch whose unit
43
+ # it also reads, and for a PR, the branch it merges into. A harvesting
44
+ # build reads the PRs that landed in +branch+.
45
+ Build = Struct.new(:key, :upstream, :branch, :pr, :harvest, keyword_init: true) do
46
+ def self.pr(number, target:) = new(key: "prs/#{number}", upstream: target, pr: true, harvest: false)
47
+ def self.branch(name, upstream: nil, harvest: false) = new(key: "branches/#{Store.escape(name)}", upstream: upstream, branch: name, harvest: harvest)
48
+
49
+ def upstream_key = upstream && "branches/#{Store.escape(upstream)}"
50
+ end
51
+
52
+ Published = Struct.new(:ref, :runs, :harvested, :deleted, keyword_init: true)
53
+
54
+ ROOT = "refs/riptide/"
55
+ RUNS = "#{ROOT}runs/".freeze
56
+ STAMPS = "#{ROOT}stamps/".freeze
57
+ TARGET = "#{ROOT}target".freeze
58
+ RETRY = "refs/riptide-retry/"
59
+
60
+ # A unit nobody wrote for this long gets deleted, like a PR closed
61
+ # without merging.
62
+ EXPIRY = 30 * 24 * 60 * 60
63
+
64
+ # How long a publish keeps retrying a lost race.
65
+ BUDGET = 120
66
+
67
+ # A set's id in the logs comes from its content, so tests sharing a
68
+ # class share one.
69
+ def self.set_id(files, scope = nil) = Digest::SHA1.hexdigest(JSON.generate([files.sort.to_h, scope].compact))[0, 16]
70
+
71
+ # One ref segment per name, so feature/a can't nest under feature.
72
+ def self.escape(name) = name.gsub("%", "%25").gsub("/", "%2F")
73
+
74
+ # Brings in the units +build+ reads, for every suite, and nothing else:
75
+ # every local riptide ref goes first. A harvesting build also ages out
76
+ # idle units and checks which PRs landed in HEAD. Riptide only reads,
77
+ # so anything going wrong here means reading less.
78
+ def self.fetch(root:, build:, remote: "origin")
79
+ git = Git.new(root)
80
+ git.delete_refs(git.refs(ROOT).keys + git.refs(RETRY).keys)
81
+ keys = [build.key, build.upstream_key].compact.uniq
82
+ specs = keys.flat_map { |key| %W[+#{RUNS}*/#{key}:#{RUNS}*/#{key} +#{STAMPS}*/#{key}:#{STAMPS}*/#{key}] }
83
+ specs << "+#{STAMPS}*:#{STAMPS}*" if build.harvest
84
+ specs << "+refs/heads/#{build.upstream}:#{TARGET}" if build.pr
85
+ git.run("fetch", "--quiet", "--atomic", "--no-tags", "--refmap=", "--no-write-fetch-head", remote, *specs)
86
+ Harvest.new(git, build, remote).run if build.harvest
87
+ end
88
+
89
+ def initialize(root:, suite:, log_dir:, remote: "origin", retained_runs: 4)
90
+ @root = root
91
+ @git = Git.new(root)
92
+ @suite = Store.escape(suite)
93
+ @log_dir = log_dir
94
+ @remote = remote
95
+ @retained_runs = retained_runs
96
+ @log = nil
97
+ @log_pid = nil
98
+ end
99
+
100
+ def runs_ref(key) = "#{RUNS}#{@suite}/#{key}"
101
+ def stamp_ref(key) = "#{STAMPS}#{@suite}/#{key}"
102
+
103
+ # Reading
104
+
105
+ # Every unit of the suite fetch left, then the logs not yet published,
106
+ # as they were the first time anything asked.
107
+ def indexes
108
+ @indexes ||= local_units.map { |key, (runs, stamp)| unit(key, runs, stamp) } << logs
109
+ end
110
+
111
+ # { line => { "owners" => [class name, ...], "called" => bool } } for a
112
+ # file version, or nil when no recorded process loaded it.
113
+ def load_facts(sha)
114
+ found = indexes.filter_map { |index| index.load_facts(sha) }
115
+ return nil if found.empty?
116
+
117
+ model = Index::Model.new
118
+ found.each { |lines| model.merge_loads(sha, lines) }
119
+ model.loads[sha].to_h { |line, fact| [line.to_i, fact] }
120
+ end
121
+
122
+ def read_blob(sha) = @git.read(sha)
123
+
124
+ # Writing, from test processes
125
+
126
+ def append_start(test) = write_record({ "type" => "start", "test" => test, "at" => Time.now.to_f })
127
+ def append_run(run) = write_record({ "type" => "run" }.merge(run.to_h.transform_keys(&:to_s)))
128
+ # +scope+ is "class" or "process" for a setup's set.
129
+ def append_set(id, files, scope: nil) = write_record({ "type" => "set", "id" => id, "files" => files, "scope" => scope }.compact)
130
+ def append_load_facts(sha, lines) = write_record({ "type" => "load", "sha" => sha, "lines" => lines })
131
+
132
+ # The tests this process's selection picked. A test it skipped already
133
+ # has a run that holds, so a new pass adds nothing.
134
+ def append_selected(tests) = write_record({ "type" => "selected", "tests" => tests })
135
+
136
+ # The runs of +index+ this process's tree no longer matches. The rest
137
+ # held here, and they're what harvesting copies.
138
+ def append_hits(index, ids) = write_record({ "type" => "hits", "ref" => index.ref, "runs" => ids.sort })
139
+
140
+ # Publishing
141
+
142
+ # Folds every log into +build+'s unit and pushes it. A harvesting build
143
+ # first copies the passing runs and open failures of the PRs that
144
+ # landed, and afterwards deletes their units.
145
+ #
146
+ # The logs go either way, so a later build never folds in this one's.
147
+ def publish(build:)
148
+ logs = Dir.glob(File.join(@log_dir, "log-*.jsonl")).sort
149
+ records = logs.flat_map { |path| read_log(path) }
150
+ seen = local_units.values.flat_map { |_, stamp| stamp ? marks_at(stamp).values.flat_map(&:to_a) : [] }.to_set
151
+ landed = build.harvest ? landed_units(build) : {}
152
+ runs, stamp = @git.resolve(runs_ref(build.key)), @git.resolve(stamp_ref(build.key))
153
+ landing = build.pr ? landing_record(build.upstream, stamp) : nil
154
+ head = @git.tree(@git.head_tree).keys.to_set
155
+ deadline = Time.now + BUDGET
156
+
157
+ loop do
158
+ model, marks, files = start_from(runs, stamp)
159
+ harvested, pins = harvest(model, marks, files, landed, records)
160
+ added = fold(model, marks, files, records, seen)
161
+ trim(model, marks, files, head)
162
+ if runs.nil? && model.runs.empty? && marks.empty?
163
+ logs.each { |path| FileUtils.rm_f(path) }
164
+ return Published.new(ref: runs_ref(build.key), runs: 0, harvested: 0, deleted: [])
165
+ end
166
+
167
+ pushed = push(build, model, marks, files, pins, landing, runs, stamp)
168
+ if pushed
169
+ # Until the push lands, a failure leaves the logs for the next
170
+ # publish, since they hold the build's failures too.
171
+ logs.each { |path| FileUtils.rm_f(path) }
172
+ @git.delete_refs(landed.flat_map { |key, _| [runs_ref(key), stamp_ref(key)] })
173
+ @git.run("update-ref", runs_ref(build.key), pushed.first)
174
+ @git.run("update-ref", stamp_ref(build.key), pushed.last)
175
+ deleted = landed.empty? ? [] : delete_units(landed)
176
+ return Published.new(ref: runs_ref(build.key), runs: added, harvested: harvested, deleted: deleted)
177
+ end
178
+ raise Error, "riptide couldn't publish #{runs_ref(build.key)} before its deadline" if Time.now > deadline
179
+
180
+ runs, stamp = refetch(build.key)
181
+ end
182
+ ensure
183
+ close_log
184
+ end
185
+
186
+ private
187
+
188
+ # { key => [runs tag, stamp tag] } for the suite's local units.
189
+ def local_units
190
+ units = Hash.new { |h, k| h[k] = [nil, nil] }
191
+ @git.refs("#{RUNS}#{@suite}/").each { |ref, tag| units[ref.delete_prefix("#{RUNS}#{@suite}/")][0] = tag }
192
+ @git.refs("#{STAMPS}#{@suite}/").each { |ref, tag| units[ref.delete_prefix("#{STAMPS}#{@suite}/")][1] = tag }
193
+ units
194
+ end
195
+
196
+ # A unit's index. One whose runs are in another format, or missing,
197
+ # still brings its open failures.
198
+ def unit(key, runs, stamp)
199
+ marks = stamp ? marks_at(stamp) : {}
200
+ return Index.empty(ref: runs_ref(key), marks: marks) unless runs && stamp && format_at(stamp) == Index::FORMAT
201
+
202
+ tree = @git.tree(runs)
203
+ Index.new(blobs: ->(path) { (sha = tree[path]) && JSON.parse(@git.read(sha)) }, paths: tree.keys, ref: runs_ref(key), marks: marks)
204
+ end
205
+
206
+ def format_at(stamp) = @git.read("#{stamp}:format")&.to_i
207
+
208
+ # { test => Set of mark ids } from a stamp, with each test's file in
209
+ # +files+. A stamp with no open failures has no marks/ at all.
210
+ def marks_at(stamp, files = {})
211
+ tree = @git.resolve("#{stamp}:marks")
212
+ return {} unless tree
213
+
214
+ @git.tree(tree).each_with_object({}) do |(_, sha), marks|
215
+ JSON.parse(@git.read(sha)).each do |key, mark|
216
+ test = JSON.parse(key)
217
+ files[test] = mark["file"] if mark["file"]
218
+ marks[test] = mark["ids"].to_set
219
+ end
220
+ end
221
+ end
222
+
223
+ def logs
224
+ model = Index::Model.new
225
+ marks = {}
226
+ fold(model, marks, {}, log_records, Set.new)
227
+ model.retain(@retained_runs)
228
+ Index.of(model.encode, marks: marks)
229
+ end
230
+
231
+ # The model and open failures a publish starts from.
232
+ def start_from(runs, stamp)
233
+ files = {}
234
+ marks = stamp ? marks_at(stamp, files) : {}
235
+ index = runs && stamp && unit(nil, runs, stamp)
236
+ [index && !index.runs.empty? ? index.model : Index::Model.new, marks, files]
237
+ end
238
+
239
+ # The units of PRs that landed in this build's branch: the ones fetch
240
+ # brought runs for. { key => [runs tag, stamp tag] }
241
+ def landed_units(build)
242
+ local_units.select do |key, (runs, stamp)|
243
+ key.start_with?("prs/") && key != build.key && runs && stamp && @git.read("#{stamp}:runs") == runs
244
+ end
245
+ end
246
+
247
+ # Copies the passing runs that held here from the landed PRs, with their
248
+ # load facts, pins and open failures. Returns how many runs, and the
249
+ # pins.
250
+ def harvest(model, marks, files, landed, records)
251
+ hits = Hash.new { |h, k| h[k] = Set.new }
252
+ read = Set.new
253
+ records.each do |record|
254
+ next unless record["type"] == "hits"
255
+
256
+ read << record["ref"]
257
+ hits[record["ref"]].merge(record["runs"])
258
+ end
259
+ pins = Set.new
260
+ count = landed.sum do |key, (runs, stamp)|
261
+ marks_at(stamp, files).each { |test, ids| (marks[test] ||= Set.new).merge(ids) }
262
+ source = unit(key, runs, stamp)
263
+ next 0 if source.runs.empty?
264
+
265
+ source = source.model
266
+ pins.merge(source.pins)
267
+ source.loads.each { |sha, lines| model.merge_loads(sha, lines) }
268
+ hit = hits[runs_ref(key)]
269
+ held = source.runs.values.flatten(1).reject { |id, _| read.include?(runs_ref(key)) && hit.include?(id) }
270
+ held.sort_by { |_, run| run.at }.count do |_, run|
271
+ sets = run.sets.to_h { |id| [id, model.add_set(source.set(id).files, source.set(id).constants, scope: source.set(id).scope)] }
272
+ body = run.body.map { |statement| statement.dup.tap { _1.set = sets[statement.set] } }
273
+ model.add_run(test: run.test, at: run.at, sets: sets.values, files: run.files, constants: run.constants, file: source.test_files[run.test],
274
+ body: body, ms: run.ms, body_line: run.body_line, body_file: run.body_file, inherited_from: run.inherited_from)
275
+ end
276
+ end
277
+ [count, pins]
278
+ end
279
+
280
+ # Adds the logs to +model+ and +marks+. A pass of a test selection
281
+ # picked is evidence, and any pass closes the open failures this build
282
+ # saw at fetch. A failure, or a test that
283
+ # started and never finished, opens one. Returns how many runs it added.
284
+ def fold(model, marks, files, records, seen)
285
+ sets = records.select { |record| record["type"] == "set" }.to_h { |record| [record["id"], record] }
286
+ decided = records.select { |record| record["type"] == "selected" }
287
+ picked = decided.flat_map { |record| record["tests"] }.to_set
288
+ ids = {}
289
+ unfinished = Hash.new(0)
290
+ added = 0
291
+ records.select { |record| %w[start run].include?(record["type"]) }.sort_by { |record| record["at"] }.each do |record|
292
+ test = record["test"]
293
+ if record["type"] == "start"
294
+ unfinished[test] += 1
295
+ next
296
+ end
297
+ unfinished[test] -= 1
298
+ files[test] = record["file"] if record["file"]
299
+ next if record["passed"].nil?
300
+
301
+ unless record["passed"]
302
+ (marks[test] ||= Set.new) << SecureRandom.hex(16)
303
+ next
304
+ end
305
+ marks[test]&.subtract(seen)
306
+ marks.delete(test) if marks[test]&.empty?
307
+ next unless record["inputs"]
308
+ next if decided.any? && !picked.include?(test)
309
+
310
+ set_ids = record["sets"].map { |id| ids[id] ||= sets[id] && model.add_set(*Index::Model.split(sets[id]["files"]), scope: sets[id]["scope"]) }
311
+ # A run whose shared set the logs lost can't be checked against anything.
312
+ next if set_ids.include?(nil)
313
+
314
+ inputs, constants = Index::Model.split(record["inputs"])
315
+ body = (record["body"] || []).map do |line, set, ms, compared, wrote, reads|
316
+ Index::Model::Statement.new(line: line, set: set && ids[set], ms: ms, compared: compared, wrote: wrote, reads: reads)
317
+ end
318
+ added += 1 if model.add_run(test: test, at: record["at"], sets: set_ids, files: inputs, constants: constants, file: record["file"],
319
+ body: body, ms: record["ms"], body_line: record["body_line"], body_file: record["body_file"],
320
+ inherited_from: record["inherited_from"])
321
+ end
322
+ unfinished.each { |test, count| (marks[test] ||= Set.new) << SecureRandom.hex(16) if count.positive? }
323
+ records.select { |record| record["type"] == "load" }.each { |record| model.merge_loads(record["sha"], record["lines"]) }
324
+ added
325
+ end
326
+
327
+ # Keeps each test's newest runs, and drops tests whose file is gone,
328
+ # runs and open failures alike.
329
+ def trim(model, marks, files, head)
330
+ gone = ->(test) { (file = model.test_files[test] || files[test]) && !head.include?(file) }
331
+ model.retain(@retained_runs, tests: model.runs.keys.reject(&gone))
332
+ marks.reject! { |test, _| gone.call(test) }
333
+ end
334
+
335
+ # Pushes the unit's runs and a new stamp in one atomic push, leased at
336
+ # what the fold started from. The two tags, or nil when another build got
337
+ # there first.
338
+ def push(build, model, marks, files, pins, landing, runs, stamp)
339
+ runs_tag = @git.tag_tree(runs_tree(model, pins, runs), "runs")
340
+ stamp_tag = @git.tag_tree(stamp_tree(marks, files, runs_tag, landing), "stamp")
341
+ leases = { runs_ref(build.key) => runs, stamp_ref(build.key) => stamp }.map { |ref, old| "--force-with-lease=#{ref}:#{old}" }
342
+ _, status = @git.run("push", "--quiet", "--atomic", *leases, @remote, "#{runs_tag}:#{runs_ref(build.key)}", "#{stamp_tag}:#{stamp_ref(build.key)}",
343
+ allow: [0, 1])
344
+ [runs_tag, stamp_tag] if status.zero?
345
+ end
346
+
347
+ # Pins keep each recorded file version fetchable. New ones come only
348
+ # from the commit the build checked out, so a staged or stashed file
349
+ # never gets pushed. A version that was never committed stays unpinned,
350
+ # and selection treats it as unavailable.
351
+ def runs_tree(model, pins, runs)
352
+ known = runs ? @git.tree(runs).values.to_set : Set.new
353
+ shas = @git.write_blobs(model.encode.transform_values { |value| JSON.generate(value) }, known: known)
354
+ pinned = model.pins | pins
355
+ committed = @git.tree(@git.head_tree).values.to_set
356
+ model.versions.each { |sha| shas["blobs/#{sha[0, 2]}/#{sha}"] = sha if pinned.include?(sha) || committed.include?(sha) }
357
+ @git.write_tree(shas)
358
+ end
359
+
360
+ def stamp_tree(marks, files, runs_tag, landing)
361
+ shards = Hash.new { |h, k| h[k] = {} }
362
+ marks.each do |test, ids|
363
+ shards[Index.shard(Index.test_key(test))][Index.test_key(test)] = { "file" => files[test], "ids" => ids.sort }.compact unless ids.empty?
364
+ end
365
+ content = { "format" => Index::FORMAT.to_s, "runs" => runs_tag }
366
+ shards.each { |shard, by_test| content["marks/#{shard}"] = JSON.generate(by_test.sort.to_h) }
367
+ entries = @git.write_blobs(content).transform_values { |sha| ["100644", sha] }
368
+ landing&.each { |path, entry| entries["landing/#{path}"] = entry }
369
+ @git.write_tree(entries)
370
+ end
371
+
372
+ # { path => [mode, object] } for the stamp's landing/ tree: the target,
373
+ # and the paths this PR changed at its merge base with the target and
374
+ # as tested. When this build can't work that out, the last stamp's
375
+ # record stands, so the PR doesn't drop out of main's harvest.
376
+ def landing_record(target, stamp)
377
+ base = @git.resolve(TARGET) && @git.merge_base("HEAD", TARGET)
378
+ unless base
379
+ warn "[riptide] couldn't find where this PR left #{target}, so its landing record stays as it was"
380
+ return stamp && @git.entries("#{stamp}:landing")
381
+ end
382
+
383
+ record = { "target" => ["100644", @git.write_blobs({ "target" => target })["target"]] }
384
+ @git.output("diff-tree", "-r", "-z", "--no-renames", base, "HEAD").split("\0").each_slice(2) do |meta, path|
385
+ old_mode, new_mode, old_sha, new_sha = meta.delete_prefix(":").split
386
+ record["base/#{path}"] = [old_mode, old_sha] unless old_mode == "000000"
387
+ record["tested/#{path}"] = [new_mode, new_sha] unless new_mode == "000000"
388
+ end
389
+ record
390
+ end
391
+
392
+ # Deletes the harvested units in one atomic push, leased at what this
393
+ # build read, so a PR that republished keeps everything.
394
+ def delete_units(landed)
395
+ refs = landed.flat_map { |key, (runs, stamp)| [[runs_ref(key), runs], [stamp_ref(key), stamp]] }
396
+ leases = refs.map { |ref, old| "--force-with-lease=#{ref}:#{old}" }
397
+ _, status = @git.run("push", "--quiet", "--atomic", *leases, @remote, *refs.map { |ref, _| ":#{ref}" }, allow: [0, 1])
398
+ status.zero? ? refs.map(&:first) : []
399
+ end
400
+
401
+ # The unit as the remote has it now, in a namespace of its own so no
402
+ # other suite's local refs move.
403
+ def refetch(key)
404
+ unit = "#{@suite}/#{key}"
405
+ @git.delete_refs(%w[runs stamps].map { |kind| "#{RETRY}#{kind}/#{unit}" }.select { |ref| @git.resolve(ref) })
406
+ @git.run("fetch", "--quiet", "--no-tags", "--refmap=", "--no-write-fetch-head", @remote, "+#{ROOT}*/#{unit}:#{RETRY}*/#{unit}")
407
+ [@git.resolve("#{RETRY}runs/#{unit}"), @git.resolve("#{RETRY}stamps/#{unit}")]
408
+ end
409
+
410
+ def write_record(record)
411
+ reopen_log unless @log_pid == Process.pid
412
+ @log.write("#{JSON.generate(record)}\n")
413
+ @log_records = nil
414
+ end
415
+
416
+ # Publishing deletes the logs it folded in, so the next record starts a
417
+ # new one.
418
+ def close_log
419
+ @log&.close
420
+ @log = nil
421
+ @log_pid = nil
422
+ @log_records = nil
423
+ end
424
+
425
+ def reopen_log
426
+ FileUtils.mkdir_p(@log_dir)
427
+ @log = File.open(File.join(@log_dir, "log-#{Process.pid}-#{SecureRandom.hex(4)}.jsonl"), "a")
428
+ @log.sync = true
429
+ @log_pid = Process.pid
430
+ end
431
+
432
+ def log_records
433
+ @log_records ||= Dir.glob(File.join(@log_dir, "log-*.jsonl")).sort.flat_map { |path| read_log(path) }
434
+ end
435
+
436
+ # A line cut short by a process killed mid-write is skipped, and its
437
+ # test counts as started and never finished.
438
+ def read_log(path)
439
+ File.foreach(path).filter_map do |line|
440
+ JSON.parse(line)
441
+ rescue JSON::ParserError
442
+ nil
443
+ end
444
+ end
445
+ end
446
+ end
@@ -0,0 +1,176 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "riptide/riptide_native"
4
+
5
+ module Riptide
6
+ # Process-wide tracer. Install it before the app loads so it sees every
7
+ # class body run.
8
+ module Tracer
9
+ Trace = Struct.new(:lines, :receivers)
10
+
11
+ # What one statement of a test body ran, and how long it took.
12
+ Statement = Struct.new(:trace, :seconds)
13
+
14
+ module CoverageWatch
15
+ def setup(*modes, **options) = watched(modes, options) { super }
16
+ def start(*modes, **options) = watched(modes, options) { super }
17
+
18
+ private
19
+
20
+ def watched(modes, options)
21
+ Tracer.oneshot! if [*modes, options].any? { |mode| mode.is_a?(Hash) && mode[:oneshot_lines] }
22
+ yield
23
+ end
24
+ end
25
+
26
+ class << self
27
+ # Also notes each file's mtime and size when Ruby compiles it, so a
28
+ # file edited mid-run can be told apart from the version that ran.
29
+ # Ruby keeps whichever path a file was required by, so a root reached
30
+ # through a symlink matches by either name.
31
+ def install(root, caller: nil)
32
+ unless SUPPORTED
33
+ @broken = "riptide was built without its tracer: #{UNSUPPORTED}"
34
+ return
35
+ end
36
+
37
+ root = File.expand_path(root)
38
+ prefixes = [root, File.realpath(root)].uniq.map { |path| "#{path}/" }
39
+ @prefixes = prefixes
40
+ _install
41
+ # The VM only looks for hooks on single iseqs while a targeted
42
+ # TracePoint is on, so one sits on a method nothing calls. Turning it
43
+ # on costs one YJIT wipe, before the app has compiled anything.
44
+ @anchor = TracePoint.new(:call) {}
45
+ @anchor.enable(target: method(:anchor))
46
+ @compiled = {}
47
+ @preloaded = ($LOADED_FEATURES + [caller].compact).uniq.filter_map do |path|
48
+ prefixes.find { |prefix| path.start_with?(prefix) }&.then { |prefix| path.delete_prefix(prefix) }
49
+ end
50
+ @compile_hook = TracePoint.new(:script_compiled) do |tp|
51
+ iseq = tp.instruction_sequence
52
+ path = iseq.absolute_path || iseq.path
53
+ prefix = path && prefixes.find { |candidate| path.start_with?(candidate) }
54
+ next unless prefix
55
+
56
+ relative = path.delete_prefix(prefix).freeze
57
+ target(iseq, relative)
58
+ stat = File.stat(path) rescue next
59
+ @compiled[relative] ||= [stat.mtime.to_r, stat.size]
60
+ end
61
+ @compile_hook.enable
62
+ end
63
+
64
+ # Aims the tracer at a compiled app file, every method and block in it
65
+ # included. Anything that goes wrong leaves the file untraced, so the
66
+ # tracer is broken for this process. The app, in the middle of loading
67
+ # the file, never sees the error.
68
+ def target(iseq, relative)
69
+ pending = [iseq]
70
+ while (current = pending.pop)
71
+ _target(current, relative)
72
+ current.each_child { |child| pending << child }
73
+ end
74
+ rescue StandardError => e
75
+ @broken ||= "couldn't trace #{relative}: #{e.class}: #{e.message}"
76
+ end
77
+
78
+ def anchor = nil
79
+
80
+ # Oneshot line coverage untraces each line after its first run, and
81
+ # riptide's hook on that line goes with it, so the two can't run
82
+ # together. Coverage started before now shows in its results, and a
83
+ # later start goes through Coverage.start or setup.
84
+ def watch_coverage
85
+ return unless defined?(::Coverage)
86
+
87
+ ::Coverage.singleton_class.prepend(CoverageWatch) unless ::Coverage.singleton_class < CoverageWatch
88
+ oneshot! if ::Coverage.running? && ::Coverage.peek_result.each_value.any? { |result| result.is_a?(Hash) && result.key?(:oneshot_lines) }
89
+ end
90
+
91
+ def oneshot!
92
+ @broken ||= "oneshot line coverage is on, and it turns off riptide's line tracing"
93
+ end
94
+
95
+ # Why the tracer missed code, or nil when it saw everything.
96
+ attr_reader :broken
97
+
98
+ # App files that loaded before the tracer was installed, like the test
99
+ # helper that installs it. Nothing can trace them, so every test
100
+ # depends on them whole.
101
+ def preloaded = @preloaded || []
102
+
103
+ # Windows nest, and lines go to the innermost one. The process's is
104
+ # always open, so code that runs outside every other window, boot
105
+ # included, lands there. It keeps no receivers.
106
+ #
107
+ # What ran in the innermost window since it opened, as { path =>
108
+ # [line, ...] } and the classes of the receivers of every in-scope
109
+ # method called.
110
+ def close_window
111
+ lines, receivers = _close_window
112
+ Trace.new(lines, receivers)
113
+ end
114
+
115
+ # What ran in the innermost window since it opened or was last drained,
116
+ # leaving it open.
117
+ def drain
118
+ lines, receivers = _drain
119
+ Trace.new(lines, receivers)
120
+ end
121
+
122
+ # Runs +body+, a test method, in a window per top-level statement, each
123
+ # starting at a line in +starts+, until close_body. The test's window
124
+ # keeps what runs around the body. A test file that compiled before the
125
+ # tracer was installed, like the first one a process loads, which
126
+ # requires the test helper itself, gets its body traced here.
127
+ def open_body(body, starts)
128
+ iseq = RubyVM::InstructionSequence.of(body)
129
+ path = iseq.absolute_path
130
+ prefix = path && @prefixes&.find { |candidate| path.start_with?(candidate) }
131
+ target(iseq, path.delete_prefix(prefix).freeze) if prefix
132
+ _open_body(iseq, starts.sort)
133
+ end
134
+
135
+ # { statement's first line => Statement } for the statements that ran
136
+ # since open_body, or nil when no body is open.
137
+ def close_body
138
+ _close_body&.transform_values { |lines, receivers, seconds| Statement.new(Trace.new(lines, receivers), seconds) }
139
+ end
140
+
141
+ # [mtime, size] of +path+ when it was first compiled, or nil.
142
+ def compiled_stat(path)
143
+ @compiled&.[](path)
144
+ end
145
+
146
+ # { path => { line => { "owners" => [class name, ...], "called" => bool } } }
147
+ # since the last drain: lines that ran because those classes were
148
+ # loading, and whether each ran as called code, a method or block body,
149
+ # rather than as a class body statement.
150
+ def drain_load_facts
151
+ called = _drain_load_called
152
+ _drain_load_facts.to_h do |path, lines|
153
+ facts = lines.to_h do |line, owners|
154
+ [line, { "owners" => owners.filter_map { |owner| Tracer.name_of(owner) }.uniq, "called" => called.dig(path, line) == true }]
155
+ end
156
+ [path, facts]
157
+ end
158
+ end
159
+
160
+ # Files whose lines ran while +mod+ was loading, including reopenings
161
+ # and concerns' included blocks.
162
+ def files_for(mod)
163
+ files = _owner_files[mod]
164
+ files ? files.keys : []
165
+ end
166
+
167
+ # A singleton class is named after the object it belongs to.
168
+ def name_of(mod)
169
+ mod = attached(mod)
170
+ mod.is_a?(Module) ? mod.name : nil
171
+ end
172
+
173
+ def attached(mod) = mod.singleton_class? ? mod.attached_object : mod
174
+ end
175
+ end
176
+ end
@@ -0,0 +1,9 @@
1
+ # frozen_string_literal: true
2
+
3
+ module Riptide
4
+ VERSION = "0.1.0"
5
+
6
+ # The Ruby minors whose VM the tracer is written for. riptide installs on
7
+ # any other and stays off there, until someone checks the new VM.
8
+ TRACED_RUBIES = %w[4.0].freeze
9
+ end