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,449 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "digest"
4
+ require "prism"
5
+ require "set"
6
+
7
+ module Riptide
8
+ # Static structure of one version of a Ruby file: what every line belongs
9
+ # to, which methods and constants it defines, and which constants each
10
+ # line references.
11
+ class Source
12
+ # +kind+ is one of :method_header, :method_body, :block_body, :constant,
13
+ # :declaration, :top or :data. +owner+ is the enclosing class or module,
14
+ # +name+ the method or constant, +line+ where its statement starts and
15
+ # +block+ where a block body's block starts. +head+ is a statement with
16
+ # its block bodies blanked, and a block body's +parent+ is its
17
+ # statement's unit. Units keep no syntax tree, so a cached Source stays
18
+ # small.
19
+ Unit = Struct.new(:kind, :owner, :name, :line, :block, :head, :parent, keyword_init: true)
20
+
21
+ # +header+ and +body+ are line ranges. +text+ is a digest of the
22
+ # definition's lines without comments or blank lines, and +slot+ says
23
+ # which class-level line it comes after, so a method reordered without
24
+ # crossing one, like a `private` or an `alias_method` naming it, can be
25
+ # told apart from one that changed. A method defined in a block has no
26
+ # slot. One in a concern's included or prepended block lands in each
27
+ # class that includes the concern, ahead of anything that class defined
28
+ # before including it, so it's marked +includers+.
29
+ Method = Struct.new(:name, :owner, :header, :body, :text, :slot, :includers, keyword_init: true)
30
+
31
+ # A constant read: the lexical nesting it was read in, innermost last,
32
+ # the path segments, and whether it started with ::. A +dynamic+ read,
33
+ # like `self.class::LIMIT` or `const_get(:LIMIT)`, only knows its last
34
+ # segment.
35
+ Reference = Struct.new(:nesting, :segments, :absolute, :dynamic, keyword_init: true)
36
+
37
+ CONSTANT_LOOKUPS = %i[const_get const_defined? const_source_location].freeze
38
+
39
+ attr_reader :methods, :constants
40
+
41
+ # nil when +text+ doesn't parse.
42
+ def self.parse(text)
43
+ result = Prism.parse(text)
44
+ result.success? ? new(text, result) : nil
45
+ end
46
+
47
+ def initialize(text, result)
48
+ @units = {}
49
+ @methods = {}
50
+ @constants = {}
51
+ @computed = Set.new
52
+ @declared = Hash.new { |h, k| h[k] = Set.new }
53
+ @aliases = {}
54
+ @block_starts = Hash.new { |h, k| h[k] = [] }
55
+ @definitions = Hash.new(0)
56
+ @bodies = Hash.new(0)
57
+ @lines = text.lines
58
+ @references = Hash.new { |h, k| h[k] = [] }
59
+ @significant = significant_lines(text, result)
60
+ @statements = {}
61
+
62
+ walk_program(result.value)
63
+ collect_statements(result.value)
64
+ collect_references(result.value, [])
65
+ magic_comments(result)
66
+ @lines = nil
67
+ end
68
+
69
+ # The top-level statements of the body of a method or block that starts
70
+ # at +line+, as line ranges, or nil. A block's call counts too, since a
71
+ # test named across lines reports where its block starts.
72
+ def statements_at(line) = @statements[line]
73
+
74
+ # nil for blank lines, comments and anything outside every unit.
75
+ def unit_at(line)
76
+ @significant.include?(line) ? @units[line] : nil
77
+ end
78
+
79
+ # Keys of the blocks that start on +line+, which is where Ruby reports a
80
+ # block being entered.
81
+ def blocks_starting_at(line)
82
+ @block_starts.fetch(line, [])
83
+ end
84
+
85
+ # Every name a class, module or constant defined here could have at
86
+ # runtime. A compact `class Billing::Card` inside `module Admin` is
87
+ # Admin::Billing::Card if Admin::Billing exists and Billing::Card if it
88
+ # doesn't, so both count.
89
+ def names_for(name)
90
+ @aliases.each_with_object([name]) do |(full, short), names|
91
+ names << name.sub(full, short) if name == full || name.start_with?("#{full}::")
92
+ end.uniq
93
+ end
94
+
95
+ def references_at(line)
96
+ @references.fetch(line, [])
97
+ end
98
+
99
+ # Whether +name+ is defined once here. When it's defined twice the last
100
+ # one wins, so reordering them changes which one runs.
101
+ def defined_once?(name)
102
+ @definitions[name] == 1
103
+ end
104
+
105
+ # Whether a class-level statement in +owner+ names +method+, the way
106
+ # `attr_accessor :status` or `delegate :total` define one without a def.
107
+ def declares?(owner, method)
108
+ @declared.key?(owner) && @declared[owner].include?(method)
109
+ end
110
+
111
+ # Whether a constant's value came from running code, like
112
+ # `LIMIT = Calc.base * 2`, rather than a literal.
113
+ def computed?(name)
114
+ @computed.include?(name)
115
+ end
116
+
117
+ # The statement's source with every block body blanked out, so a
118
+ # one-line `scope :x, -> { ... }` can tell a changed lambda from a
119
+ # changed declaration.
120
+ def self.head_of(statement)
121
+ text = statement.slice.b
122
+ offset = statement.location.start_offset
123
+ # Prism's offsets are bytes, so the cutting is too.
124
+ block_bodies(statement).sort_by { |b| -b.location.start_offset }.each do |body|
125
+ text.bytesplice(body.location.start_offset - offset, body.location.length, "")
126
+ end
127
+ text
128
+ end
129
+
130
+ def self.block_bodies(node)
131
+ node.compact_child_nodes.flat_map do |child|
132
+ if (child.is_a?(Prism::BlockNode) || child.is_a?(Prism::LambdaNode)) && child.body
133
+ [child.body]
134
+ else
135
+ block_bodies(child)
136
+ end
137
+ end
138
+ end
139
+
140
+ private
141
+
142
+ IGNORED_TOKENS = %i[COMMENT NEWLINE IGNORED_NEWLINE EMBDOC_BEGIN EMBDOC_LINE EMBDOC_END EOF].freeze
143
+
144
+ # Lines carrying at least one real token. Heredoc content counts, a
145
+ # comment or blank line outside a string doesn't, and everything after
146
+ # __END__ is data the file can read.
147
+ def significant_lines(text, result)
148
+ lines = Set.new
149
+ Prism.lex(text).value.each do |token, _state|
150
+ next if IGNORED_TOKENS.include?(token.type)
151
+
152
+ location = token.location
153
+ if token.type == :__END__
154
+ (location.start_line..text.count("\n") + 1).each { |line| lines << line; @units[line] = Unit.new(kind: :data) }
155
+ break
156
+ end
157
+ last = location.end_column.zero? && location.end_line > location.start_line ? location.end_line - 1 : location.end_line
158
+ (location.start_line..last).each { |line| lines << line }
159
+ end
160
+ lines
161
+ end
162
+
163
+ def mark(range, unit)
164
+ range.each { |line| @units[line] = unit unless @units[line]&.kind == :data }
165
+ end
166
+
167
+ # `# frozen_string_literal: true` and its kind change how the whole file
168
+ # runs, so they're data, not comments.
169
+ def magic_comments(result)
170
+ result.magic_comments.each do |comment|
171
+ line = comment.key_loc.start_line
172
+ @significant << line
173
+ @units[line] = Unit.new(kind: :data)
174
+ end
175
+ end
176
+
177
+ # A node's lines, including the body of any heredoc it opens: Prism
178
+ # ends `TEXT = <<~T` on its first line.
179
+ def lines_of(node)
180
+ node.location.start_line..last_line(node)
181
+ end
182
+
183
+ def last_line(node)
184
+ own = node.respond_to?(:closing_loc) && node.closing_loc && node.respond_to?(:heredoc?) && node.heredoc? ? node.closing_loc.start_line : node.location.end_line
185
+ node.compact_child_nodes.map { |child| last_line(child) }.push(own).max
186
+ end
187
+
188
+ def walk_program(program)
189
+ slots(program.statements.body, "Object").each do |statement, slot|
190
+ case statement
191
+ when Prism::ClassNode, Prism::ModuleNode then walk_namespace(statement, nil)
192
+ when Prism::DefNode then define_method(statement, "Object", statement, slot: slot)
193
+ # A literal top-level constant is read like any other. One whose
194
+ # value ran code stays top-level, since that code ran at boot.
195
+ when Prism::ConstantWriteNode
196
+ literal?(statement.value) ? define_constant(statement, nil, statement.name.to_s) : top(statement)
197
+ else
198
+ top(statement)
199
+ end
200
+ end
201
+ end
202
+
203
+ def collect_statements(node)
204
+ body = case node
205
+ when Prism::DefNode then node.body
206
+ when Prism::BlockNode then node.body
207
+ end
208
+ if body
209
+ body = body.statements if body.is_a?(Prism::BeginNode)
210
+ nodes = body.is_a?(Prism::StatementsNode) ? body.body : [body]
211
+ ranges = nodes.compact.map { |statement| (statement.location.start_line..last_line(statement)) }
212
+ @statements[node.location.start_line] ||= ranges unless ranges.empty?
213
+ end
214
+ if node.is_a?(Prism::CallNode) && node.block.is_a?(Prism::BlockNode)
215
+ collect_statements(node.block)
216
+ @statements[node.location.start_line] ||= @statements[node.block.location.start_line]
217
+ end
218
+ node.compact_child_nodes.each { |child| collect_statements(child) unless node.is_a?(Prism::CallNode) && child.equal?(node.block) }
219
+ end
220
+
221
+ def top(statement)
222
+ unit = statement_unit(:top, nil, nil, statement)
223
+ mark(lines_of(statement), unit)
224
+ walk_blocks(statement, nil, parent: unit)
225
+ end
226
+
227
+ # No constant read and no call into the app's code. A method called on
228
+ # a literal, like `%w[a b].freeze`, runs Ruby's own code.
229
+ def literal?(node)
230
+ case node
231
+ when Prism::ConstantReadNode, Prism::ConstantPathNode then false
232
+ when Prism::CallNode then !node.receiver.nil? && node.block.nil? && node.compact_child_nodes.all? { |child| literal?(child) }
233
+ else node.compact_child_nodes.all? { |child| literal?(child) }
234
+ end
235
+ end
236
+
237
+ # The header runs to the end of the superclass, which can take more than
238
+ # a line, like `Struct.new(` with its members below.
239
+ def walk_namespace(node, outer)
240
+ name = namespace_name(outer, node)
241
+ start = node.location.start_line
242
+ header_end = [node.constant_path, (node.superclass if node.is_a?(Prism::ClassNode))].compact.map { |part| part.location.end_line }.max
243
+ mark(start..header_end, Unit.new(kind: :declaration, owner: name, line: start))
244
+ walk_body(node.body, name)
245
+ end
246
+
247
+ # `class ::Widget` is Widget wherever it's written.
248
+ def namespace_name(outer, node)
249
+ path = node.constant_path.slice
250
+ return path.delete_prefix("::") if path.start_with?("::") || outer.nil?
251
+
252
+ name = "#{outer}::#{path}"
253
+ @aliases[name] = path if path.include?("::")
254
+ name
255
+ end
256
+
257
+ def walk_body(body, owner, singleton: false)
258
+ statements = body.is_a?(Prism::StatementsNode) ? body.body : [body].compact
259
+ slots(statements, singleton ? "#{owner}." : owner).each { |statement, slot| walk_statement(statement, owner, singleton: singleton, slot: slot) }
260
+ end
261
+
262
+ # Pairs each statement in a body with the class-level line it comes
263
+ # after: which body of +owner+ this is, that line's digest, and which of
264
+ # the lines with that digest it is. Methods don't count as lines here,
265
+ # since reordering them changes nothing. The first method after a line
266
+ # gets a slot to itself, since a line like `sig` or `desc` applies to
267
+ # whichever method comes next.
268
+ def slots(statements, owner)
269
+ body = @bodies[owner] += 1
270
+ seen = Hash.new(0)
271
+ slot = [body]
272
+ statements.map do |statement|
273
+ if statement.is_a?(Prism::DefNode) || defines_through_call?(statement)
274
+ pair = [statement, slot]
275
+ slot = slot.take(3) + [:after]
276
+ else
277
+ digest = Digest::SHA1.hexdigest(statement.slice)
278
+ slot = [body, digest, seen[digest] += 1]
279
+ pair = [statement, slot]
280
+ end
281
+ pair
282
+ end
283
+ end
284
+
285
+ def walk_statement(statement, owner, singleton: false, slot: nil)
286
+ case statement
287
+ when Prism::ClassNode, Prism::ModuleNode
288
+ walk_namespace(statement, owner)
289
+ when Prism::SingletonClassNode
290
+ mark(statement.location.start_line..statement.location.start_line, Unit.new(kind: :declaration, owner: owner, line: statement.location.start_line))
291
+ walk_body(statement.body, owner, singleton: true)
292
+ when Prism::DefNode
293
+ define_method(statement, owner, statement, singleton: singleton, slot: slot)
294
+ when ->(node) { defines_through_call?(node) }
295
+ # `private def charge` and `memoize def total` define a method too.
296
+ statement.arguments.arguments.grep(Prism::DefNode).each { |node| define_method(node, owner, statement, singleton: singleton, slot: slot) }
297
+ when Prism::ConstantWriteNode, Prism::ConstantOrWriteNode, Prism::ConstantAndWriteNode, Prism::ConstantOperatorWriteNode
298
+ define_constant(statement, owner, [owner, statement.name].compact.join("::"))
299
+ when Prism::ConstantPathWriteNode, Prism::ConstantPathOrWriteNode, Prism::ConstantPathAndWriteNode, Prism::ConstantPathOperatorWriteNode
300
+ define_constant(statement, owner, [owner, statement.target.slice.delete_prefix("::")].compact.join("::"))
301
+ when ->(node) { node.is_a?(Prism::MultiWriteNode) && constant_targets(node).any? }
302
+ define_constant(statement, owner, constant_targets(statement).map { |target| [owner, target.slice.delete_prefix("::")].compact.join("::") })
303
+ else
304
+ unit = statement_unit(:declaration, owner, nil, statement)
305
+ mark(lines_of(statement), unit)
306
+ walk_blocks(statement, owner, parent: unit)
307
+ declared(statement, owner)
308
+ nested_constants(statement, owner)
309
+ end
310
+ end
311
+
312
+ def constant_targets(node)
313
+ (node.lefts + [node.rest&.expression].compact + node.rights).grep(Prism::ConstantTargetNode) +
314
+ (node.lefts + node.rights).grep(Prism::ConstantPathTargetNode)
315
+ end
316
+
317
+ def declared(statement, owner)
318
+ return unless statement.is_a?(Prism::CallNode) && statement.receiver.nil?
319
+
320
+ statement.arguments&.arguments&.each do |argument|
321
+ next unless argument.is_a?(Prism::SymbolNode) || argument.is_a?(Prism::StringNode)
322
+
323
+ name = argument.unescaped
324
+ @declared[owner].merge([name, "#{name}=", "#{name}?"])
325
+ end
326
+ end
327
+
328
+ # A constant assigned inside a class-level `if` or `begin` is still a
329
+ # constant.
330
+ def nested_constants(node, owner)
331
+ node.compact_child_nodes.each do |child|
332
+ case child
333
+ when Prism::DefNode, Prism::ClassNode, Prism::ModuleNode, Prism::BlockNode, Prism::LambdaNode then next
334
+ when Prism::ConstantWriteNode then define_constant(child, owner, [owner, child.name].compact.join("::"))
335
+ else nested_constants(child, owner)
336
+ end
337
+ end
338
+ end
339
+
340
+ def concern_block?(call, block, name)
341
+ call.is_a?(Prism::CallNode) && call.name == name && call.receiver.nil? && call.block.equal?(block)
342
+ end
343
+
344
+ def defines_through_call?(node)
345
+ node.is_a?(Prism::CallNode) && node.receiver.nil? && node.block.nil? && node.arguments&.arguments&.grep(Prism::DefNode)&.any?
346
+ end
347
+
348
+ # +names+ is one name, or several for `LO, HI = 1, 9`, which share a
349
+ # unit since a change to the line can't say which one it touched.
350
+ def define_constant(statement, owner, names)
351
+ Array(names).each do |name|
352
+ @constants[name] = lines_of(statement)
353
+ @computed << name if statement.respond_to?(:value) && !literal?(statement.value)
354
+ end
355
+ unit = statement_unit(:constant, owner, names, statement)
356
+ mark(lines_of(statement), unit)
357
+ walk_blocks(statement, owner, parent: unit, constant: Array(names).first)
358
+ end
359
+
360
+ # +within+ is the module the method lands in, when that isn't +owner+,
361
+ # the class whose file it's in.
362
+ def define_method(node, owner, statement, singleton: false, slot: nil, within: owner, includers: false)
363
+ singleton ||= node.receiver.is_a?(Prism::SelfNode)
364
+ name = "#{within}#{singleton ? "." : "#"}#{node.name}"
365
+ header_end = (node.rparen_loc || node.parameters&.location || node.name_loc).end_line
366
+ header = node.location.start_line..header_end
367
+ body = (header_end + 1)..node.location.end_line
368
+
369
+ @definitions[name] += 1
370
+ @methods[name] = Method.new(name: name, owner: owner, header: header, body: body, text: digest_of(lines_of(statement)), slot: slot, includers: includers)
371
+ line = statement.location.start_line
372
+ mark(header, Unit.new(kind: :method_header, owner: owner, name: name, line: line))
373
+ mark(body, Unit.new(kind: :method_body, owner: owner, name: name, line: line))
374
+ end
375
+
376
+ def digest_of(lines)
377
+ Digest::SHA1.hexdigest(lines.select { |line| @significant.include?(line) }.map { |line| @lines[line - 1] }.join)
378
+ end
379
+
380
+ def statement_unit(kind, owner, name, statement)
381
+ head = Source.block_bodies(statement).empty? ? nil : Source.head_of(statement)
382
+ Unit.new(kind: kind, owner: owner, name: name, line: statement.location.start_line, head: head)
383
+ end
384
+
385
+ # Block bodies inside a class-level statement. Methods and classes
386
+ # defined in one, like Struct.new(...) do def x; end end, keep their
387
+ # own kind.
388
+ def walk_blocks(node, owner, parent:, constant: nil)
389
+ node.compact_child_nodes.each do |child|
390
+ unless (child.is_a?(Prism::BlockNode) || child.is_a?(Prism::LambdaNode)) && child.body
391
+ walk_blocks(child, owner, parent: parent, constant: constant)
392
+ next
393
+ end
394
+
395
+ block = child.location.start_line
396
+ @block_starts[block] << block unless @block_starts[block].include?(block)
397
+ mark(lines_of(child.body), Unit.new(kind: :block_body, owner: owner, line: parent.line, block: block, parent: parent))
398
+ statements = child.body.is_a?(Prism::StatementsNode) ? child.body.body : [child.body]
399
+ # A concern's class_methods block defines its methods in the
400
+ # concern's ClassMethods, which every includer extends.
401
+ within = concern_block?(node, child, :class_methods) ? "#{owner}::ClassMethods" : constant || owner
402
+ includers = concern_block?(node, child, :included) || concern_block?(node, child, :prepended)
403
+ statements.each do |inner|
404
+ case inner
405
+ when Prism::DefNode then define_method(inner, constant || owner, inner, within: within, includers: includers)
406
+ when Prism::ClassNode, Prism::ModuleNode then walk_namespace(inner, owner)
407
+ else walk_blocks(inner, owner, parent: parent, constant: constant)
408
+ end
409
+ end
410
+ end
411
+ end
412
+
413
+ def collect_references(node, nesting)
414
+ case node
415
+ when Prism::ClassNode, Prism::ModuleNode
416
+ collect_references(node.superclass, nesting) if node.is_a?(Prism::ClassNode) && node.superclass
417
+ name = namespace_name(nesting.last, node)
418
+ inner = nesting + names_for(name).reverse
419
+ collect_references(node.body, inner) if node.body
420
+ return
421
+ when Prism::ConstantReadNode
422
+ record_reference(node, nesting, [node.name.to_s], absolute: false)
423
+ return
424
+ when Prism::ConstantPathNode
425
+ parts = begin
426
+ node.full_name_parts.map(&:to_s)
427
+ rescue Prism::ConstantPathNode::DynamicPartsInConstantPathError
428
+ nil
429
+ end
430
+ if parts
431
+ absolute = parts.first.empty?
432
+ record_reference(node, nesting, absolute ? parts.drop(1) : parts, absolute: absolute)
433
+ return
434
+ end
435
+ record_reference(node, nesting, [node.name.to_s], absolute: false, dynamic: true)
436
+ when Prism::CallNode
437
+ name = CONSTANT_LOOKUPS.include?(node.name) && node.arguments&.arguments&.first
438
+ if name.is_a?(Prism::SymbolNode) || name.is_a?(Prism::StringNode)
439
+ record_reference(node, nesting, [name.unescaped.split("::").last], absolute: false, dynamic: true)
440
+ end
441
+ end
442
+ node.compact_child_nodes.each { |child| collect_references(child, nesting) }
443
+ end
444
+
445
+ def record_reference(node, nesting, segments, absolute:, dynamic: false)
446
+ @references[node.location.start_line] << Reference.new(nesting: nesting, segments: segments, absolute: absolute, dynamic: dynamic)
447
+ end
448
+ end
449
+ end