Class: Mutineer::Project::SubjectVisitor

Inherits:
Prism::Visitor
  • Object
show all
Defined in:
lib/mutineer/project.rb

Overview

Walks an AST, maintaining a namespace stack, emitting Subjects. Nested inside Project to signal its private role.

Defined Under Namespace

Classes: WrittenName

Constant Summary collapse

CLASS_BUILDERS =

Calls whose block is the body of the class they build: receiver name => method.

{ "Data" => :define, "Struct" => :new, "Class" => :new, "Module" => :new }.freeze
CONCERN_BLOCKS =

ActiveSupport::Concern calls whose block another module or class runs (see #concern_block).

%i[class_methods included prepended].freeze
NAME_TAKERS =

Calls whose first argument names a method they reach (see #placeable_hook).

%i[method instance_method send public_send __send__].freeze
CONSTANT_PATH =

A constant name, or a path of them; Ruby allows Unicode in both.

/\A[[:upper:]][[:word:]]*(?:::[[:upper:]][[:word:]]*)*\z/
SCOPE_STATE =

Visitor state a class/module body or builder block sets for what it contains.

%i[@namespace_stack @lexical_stack @module_function_active @block_owner @block_namespace
@owner_unknown @singleton_depth @singleton_cref @namespace_unknown @anonymous_block @body
@self_unknown @self_scope @singleton_uncertain @hook_block @hook_call @hook_uses].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(file, plain_calls = Set.new) ⇒ SubjectVisitor

Builds a subject visitor.

Parameters:

  • file (String) —

    source file path being visited.

  • plain_calls (Set<Prism::CallNode>) (defaults to: Set.new) —

    the file's call statements on a plain path (see Mutineer::Project.plain_path_calls); only these hook calls can be placed.



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
# File 'lib/mutineer/project.rb', line 206

def initialize(file, plain_calls = Set.new)
  @file = file
  @plain_calls = plain_calls
  @namespace_stack = []
  @lexical_stack = [] # class/module names as written, `::X` kept (#145)
  @subjects = []
  @singleton_depth = 0
  @module_function_active = false # bareword `module_function` seen in this module body
  @module_function_names = []     # [module key, name] from `module_function :a` / `module_function def` (#98)
  @subject_keys = []              # the module key of each subject, by index
  @body = Object.new              # identifies the class/module body or builder block being visited
  @block_owner = nil
  @block_namespace = nil
  @owner_unknown = false
  @assigned = nil
  @singleton_cref = nil # the singleton class name, in a builder block inside `class << self`
  @namespace_unknown = false # the namespace is under a singleton class (#208) or a block's `self` (#229)
  @anonymous_block = false   # inside a builder block not assigned to a constant
  @self_unknown = false      # inside a def or a block that is not a builder, so `self` is not the namespace
  @self_scope = nil          # the def or block whose `self` the code runs with
  @singleton_uncertain = false # the open `class << self` was inside a def or a non-builder block
  @concern_modules = Set.new   # the {#module_key} of each module that ran `extend ActiveSupport::Concern`
  @hook_block = false          # inside a concern's `included` or `prepended` block (see {#hook_block?})
  @enclosing_subject = nil     # the subject of the def being visited, for a nested def (#290)
  @hook_call = nil             # that block's call node, when reload can place its defs (see {#placeable_hook})
  @hook_uses = Set.new         # the names that block calls outside its def bodies
  super()
end

Instance Attribute Details

#subjects ⇒ Object (readonly)

Returns the value of attribute subjects.



199
200
201
# File 'lib/mutineer/project.rb', line 199

def subjects
  @subjects
end

Instance Method Details

#assigned_owner(node) ⇒ Array(String, Array<String>, Boolean) (private)

Resolves the constant an assignment writes the way Ruby does. X is in the current namespace, ::X and a path at the top level start from Object, and self::X is under the current class (the built class inside a builder block). In a block that does not build a class, self may be any object, so self::X there has its owner unknown (#229). Any other path is looked up at run time, so its owner is unknown and the subject is named as written. Lexically inside class << self, even within a builder block there, the constant belongs to the singleton class, which has no constant path, so its owner is unknown too, as is X or self::X in a class or module opened there (#208). A ::X there is named X, still unknown (see #with_namespace).

Parameters:

  • node (Prism::Node) —

    constant assignment.

Returns:

  • (Array(String, Array<String>, Boolean)) —

    owner, namespace, unknown.



548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
# File 'lib/mutineer/project.rb', line 548

def assigned_owner(node)
  if @singleton_cref || @singleton_depth.positive?
    written = node.respond_to?(:target) ? node.target.slice : node.name.to_s
    return [nil, written.start_with?("::") ? [written.delete_prefix("::")] : [singleton_name, written], true]
  end
  unless node.respond_to?(:target)
    namespace = @namespace_stack + [node.name.to_s]
    return @namespace_unknown ? [nil, namespace, true] : named_owner(namespace)
  end

  names = []
  path = node.target
  while path.is_a?(Prism::ConstantPathNode)
    names.unshift(path.name.to_s)
    path = path.parent
  end
  # see {#with_namespace}; in a builder block too, so a later `module self::X` there matches it
  if path.is_a?(Prism::SelfNode) && (@self_unknown || @block_namespace)
    names[0] = WrittenName.new(names[0], @self_scope)
  end
  if path.is_a?(Prism::SelfNode) && (@self_unknown || @namespace_unknown && !@anonymous_block)
    return [nil, (@block_namespace || @namespace_stack) + names, true]
  end

  base =
    case path
    when nil then []
    when Prism::SelfNode then @block_namespace || @namespace_stack unless @owner_unknown
    when Prism::ConstantReadNode then [path.name.to_s] if @namespace_stack.empty?
    end
  return [nil, [node.target.slice], true] unless base

  @namespace_unknown ? [nil, base + names, true] : named_owner(base + names)
end

#assigned_value(node) ⇒ Prism::Node? (private)

The value an assignment stores: the last statement inside parentheses or a begin without rescue, which Ruby returns from them.

Parameters:

  • node (Prism::Node) —

    assigned expression.

Returns:

  • (Prism::Node, nil)


615
616
617
618
619
620
621
622
623
624
625
626
# File 'lib/mutineer/project.rb', line 615

def assigned_value(node)
  loop do
    body =
      case node
      when Prism::ParenthesesNode then node.body
      when Prism::BeginNode then node.statements unless node.rescue_clause
      end
    return node unless body

    node = body.is_a?(Prism::StatementsNode) ? body.body.last : body
  end
end

#builds_class?(node) ⇒ Boolean (private)

True when the node is Data.define, Struct.new, Class.new or Module.new with a block.

Parameters:

  • node (Prism::Node, nil) —

    node.

Returns:

  • (Boolean)


632
633
634
635
# File 'lib/mutineer/project.rb', line 632

def builds_class?(node)
  node.is_a?(Prism::CallNode) && node.block.is_a?(Prism::BlockNode) &&
    CLASS_BUILDERS[node.receiver&.slice&.delete_prefix("::")] == node.name
end

#concern_block(node) ⇒ Symbol? (private)

Sorts an ActiveSupport::Concern block by where redefine can load its defs. ActiveSupport evaluates a class_methods block in the module's ClassMethods, which it extends onto every includer, so the test calls Includer.name on that module's method, not on the concern (#252). In a class or module body, or a builder block, with a known owner, that module is <namespace>::ClassMethods. The block keeps the lexical scope, so redefine reopens the concern's chain and loads the mutant with ::Concern::ClassMethods.class_eval. In a def, a block that does not build a class (Rails' concerning :Name do), class << self, or under an owner no constant names (an unassigned Module.new), no constant here names that ClassMethods. ActiveSupport evaluates an included or prepended block in each includer, which no constant names either. The call has no receiver or self, no arguments, and a block.

Another library can define methods with these names and run the block in the module itself. So a class_methods block counts only in a module that ran extend ActiveSupport::Concern earlier in this file, in this body or an earlier one (#module_key). Any other block with these names is unplaceable: guessing its owner would load a mutant where the tests never call it.

Parameters:

  • node (Prism::CallNode) —

    call node.

Returns:

  • (Symbol, nil) —

    :class_methods when redefine can name the module, :owner_unknown for any other Concern block, or nil for any other call.



659
660
661
662
663
664
665
# File 'lib/mutineer/project.rb', line 659

def concern_block(node)
  return unless CONCERN_BLOCKS.include?(node.name) && node.arguments.nil? && node.block.is_a?(Prism::BlockNode)
  return unless node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)
  placeable = node.name == :class_methods && !@self_unknown && @singleton_depth.zero? && !@owner_unknown &&
              @concern_modules.include?(module_key)
  placeable ? :class_methods : :owner_unknown
end

#extract_constant_name(node) ⇒ String? (private)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Extracts a constant name from a Prism constant node.

Parameters:

  • node (Prism::Node) —

    constant node.

Returns:

  • (String, nil) —

    constant name.



784
785
786
787
788
789
790
791
# File 'lib/mutineer/project.rb', line 784

def extract_constant_name(node)
  case node
  when Prism::ConstantReadNode
    node.name.to_s
  when Prism::ConstantPathNode
    [extract_constant_name(node.parent), node.name.to_s].compact.join("::")
  end
end

#hook_block?(node) ⇒ Boolean (private)

True for an included or prepended block of a module that ran extend ActiveSupport::Concern earlier in this file (see #concern_block). ActiveSupport runs the block only when a class first includes or prepends the concern, so loading the file again stores the new block but never runs it in a class that already has the concern (#256). Reload can still place a def that sits directly in such a block (see #placeable_hook and #reload_hook_call_for, #297); anything else the block defines, a nested class or a builder block included, stays as the original wrote it.

Parameters:

  • node (Prism::CallNode) —

    a call #concern_block sorted as a concern block.

Returns:

  • (Boolean)


678
679
680
# File 'lib/mutineer/project.rb', line 678

def hook_block?(node)
  %i[included prepended].include?(node.name) && @concern_modules.include?(module_key)
end

#module_key ⇒ String, Object (private)

The module a module_function call and a def are matched by: its joined namespace, so a module reopened later in the file matches (#216), and module A::B matches nested module A; module B. An unknown owner that an anonymous builder block owns, or whose name has no WrittenName segment and is not built only from constant names (see #named_segment?), may be shared by another module, so it is matched only within this body (#208). Otherwise a name with a WrittenName segment is matched by that segment's scope and text, so openings under one self match each other, but not those under another, whether the owner is known or not (#229).

Returns:

  • (String, Object)


438
439
440
441
442
443
444
445
# File 'lib/mutineer/project.rb', line 438

def module_key
  namespace = @block_namespace || @namespace_stack
  written = written?(namespace)
  return @body if @owner_unknown && (@anonymous_block || !written && !namespace.all? { |s| named_segment?(s) })
  return namespace.join("::") unless written

  namespace.map { |s| s.is_a?(WrittenName) ? "#{s.scope.object_id}:#{s}" : s }.join("::")
end

#named_owner(namespace) ⇒ Array(String, Array<String>, Boolean) (private)

The owner for a resolved namespace, root-anchored so the redefine wrapper loads onto that constant from any nesting.

Parameters:

  • namespace (Array<String>) —

    resolved namespace.

Returns:

  • (Array(String, Array<String>, Boolean))


606
607
608
# File 'lib/mutineer/project.rb', line 606

def named_owner(namespace)
  ["::#{namespace.join("::")}", namespace, false]
end

#named_segment?(segment) ⇒ Boolean (private)

True when a namespace segment is a constant name, or a singleton class (#<Class:App::M>) of constant names. A written path or #<anonymous> is not, nor is a singleton class name built on one (WrittenName).

Parameters:

  • segment (String) —

    namespace segment.

Returns:

  • (Boolean)


461
462
463
464
# File 'lib/mutineer/project.rb', line 461

def named_segment?(segment)
  !segment.is_a?(WrittenName) && segment.gsub(/#<Class:|>/, "").match?(CONSTANT_PATH) &&
    (segment.start_with?("#<Class:") || !segment.include?("::"))
end

#placeable_hook(node) ⇒ Array(Prism::CallNode, Set<Symbol>), Array(nil, Set<Symbol>) (private)

The hook call and the names its block calls outside its def bodies, when reload can place the block's defs (#297), else nil and an empty set. The call must be on a plain path (Mutineer::Project.plain_path_calls), so the statement the mutant file adds before it runs exactly when the call runs. An alias in the block keeps the original body, so a block with any alias or alias_method places nothing. The names come from bare calls, self. calls and the name given to method, instance_method, send, public_send or __send__, in every nested block and lambda too: discovery cannot tell a block that runs at once from one that runs later. A name such a call computes at runtime places nothing.

Parameters:

  • node (Prism::CallNode) —

    the hook call.

Returns:

  • (Array(Prism::CallNode, Set<Symbol>), Array(nil, Set<Symbol>))


695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
# File 'lib/mutineer/project.rb', line 695

def placeable_hook(node)
  uses = Set.new
  return [nil, uses] unless @plain_calls.include?(node)

  nodes = [node.block.body].compact
  while (current = nodes.pop)
    next if current.is_a?(Prism::DefNode)
    return [nil, Set.new] if current.is_a?(Prism::AliasMethodNode)

    if current.is_a?(Prism::CallNode) && (current.receiver.nil? || current.receiver.is_a?(Prism::SelfNode))
      return [nil, Set.new] if current.name == :alias_method

      uses << current.name
      if NAME_TAKERS.include?(current.name) && (name_arg = current.arguments&.arguments&.first)
        # A runtime name may be any def in the block.
        return [nil, Set.new] unless name_arg.is_a?(Prism::SymbolNode) || name_arg.is_a?(Prism::StringNode)

        uses << name_arg.unescaped.to_sym
      end
    end
    nodes.concat(current.compact_child_nodes)
  end
  [node, uses]
end

#preserving_scope { ... } ⇒ void (private)

This method returns an undefined value.

Runs the block and then restores every SCOPE_STATE variable, so a nested body's state never leaks out of it.

Yields:

  • the nested visit.



527
528
529
530
531
532
# File 'lib/mutineer/project.rb', line 527

def preserving_scope
  saved = SCOPE_STATE.map { |name| instance_variable_get(name) }
  yield
ensure
  SCOPE_STATE.zip(saved) { |name, value| instance_variable_set(name, value) }
end

#promote_module_functions! ⇒ void

This method returns an undefined value.

Promote module_function :name / module_function def name subjects to singleton after the full walk — the naming call may appear before or after the def, so it can't be decided at visit_def_node time (#20). Only methods of the module that made the call are promoted (#98), matched by #module_key.



241
242
243
244
245
246
247
248
249
250
251
# File 'lib/mutineer/project.rb', line 241

def promote_module_functions!
  return if @module_function_names.empty?

  named = @module_function_names.to_set
  @subjects.each_with_index do |s, i|
    next unless named.include?([@subject_keys[i], s.name])

    s.singleton = true
    s.reload_hook_call = nil # a module function has a second, private copy no hook def placement makes
  end
end

#reload_hook_call_for(node) ⇒ Prism::CallNode? (private)

The hook call of the block this def sits in directly, when reload can place the def (#297), else nil. The def must be in the block itself, or in its class << self without a receiver: not in a def, a nested class or module, or another block. module_function gives the def a second, private copy, and a name the block itself uses kept the original's result, so neither is placeable. An explicit receiver other than self can be bound only inside the hook, which the extracted def does not keep.

Parameters:

  • node (Prism::DefNode) —

    the def being recorded.

Returns:

  • (Prism::CallNode, nil)


730
731
732
733
734
735
736
737
# File 'lib/mutineer/project.rb', line 730

def reload_hook_call_for(node)
  return unless @hook_call && @self_scope.equal?(@hook_call.block) && !@module_function_active
  return if node.receiver && !node.receiver.is_a?(Prism::SelfNode)
  return if @singleton_depth > 1 || (@singleton_depth == 1 && node.receiver)
  return if @hook_uses.include?(node.name)

  @hook_call
end

#root_anchored?(node) ⇒ Boolean (private)

True when a constant path starts with :: (e.g. ::X or ::A::B).

Parameters:

  • node (Prism::Node) —

    constant path node.

Returns:

  • (Boolean)


774
775
776
777
# File 'lib/mutineer/project.rb', line 774

def root_anchored?(node)
  node = node.parent while node.is_a?(Prism::ConstantPathNode) && node.parent
  node.is_a?(Prism::ConstantPathNode)
end

#self_rooted?(node) ⇒ Boolean (private)

True when a constant path starts with self (e.g. self::X).

Parameters:

  • node (Prism::Node) —

    constant path node.

Returns:

  • (Boolean)


765
766
767
768
# File 'lib/mutineer/project.rb', line 765

def self_rooted?(node)
  node = node.parent while node.is_a?(Prism::ConstantPathNode)
  node.is_a?(Prism::SelfNode)
end

#singleton_name ⇒ String (private)

Names the singleton class that owns the constants written here: class << self opens that of the current class (the built class inside a builder block), and a builder block inside class << self keeps the enclosing one. A block not assigned to a constant builds a class with no name, written #<anonymous>. Each nested class << self opens the singleton class of the one around it. A name built on a written path or #<anonymous>, or opened where self may be another object (in a def or a non-builder block), is a WrittenName (see #module_key).

Returns:

  • (String) —

    e.g. #<Class:App>, or #<Class:#<Class:App>> two deep.



592
593
594
595
596
597
598
599
# File 'lib/mutineer/project.rb', line 592

def singleton_name
  return @singleton_cref unless @singleton_depth.positive?

  base = @anonymous_block ? @namespace_stack + ["#<anonymous>"] : @block_namespace || @namespace_stack
  name = @singleton_depth.times.reduce(base.join("::")) { |inner, _| "#<Class:#{inner}>" }
  named = !@singleton_uncertain && (@owner_unknown ? base.all? { |s| named_segment?(s) } : !written?(base))
  named ? name : WrittenName.new(name)
end

#visit_block_node(node) ⇒ void Also known as: visit_lambda_node

This method returns an undefined value.

A block that does not build a class may run with any self (class_eval, instance_eval, a callback), so a class << self in it names a singleton class Mutineer cannot be sure of (#216). A lambda is treated the same.

Parameters:

  • node (Prism::BlockNode, Prism::LambdaNode) —

    block or lambda node.



335
336
337
338
339
340
341
342
343
# File 'lib/mutineer/project.rb', line 335

def visit_block_node(node)
  return super if node.equal?(@self_scope) # a builder block

  saved_self = [@self_unknown, @self_scope]
  @self_unknown = true
  @self_scope = node
  super
  @self_unknown, @self_scope = saved_self
end

#visit_call_node(node) ⇒ void

This method returns an undefined value.

Track module_function so its methods are recorded as singletons (#20) — the called form is the singleton method on the module object. Bareword module_function flips all SUBSEQUENT defs in this body; the argument forms (:sym, def) name methods promoted after the walk. A builder block's defs belong to the class it builds; one not assigned to a constant has no name, so its subjects are marked owner_unknown, and a module_function :name in it promotes nothing. Elsewhere it promotes the methods of the same module, matched by #module_key. A module that runs extend ActiveSupport::Concern is a concern from then on in this file. A class_methods block in its body (see #concern_block) is visited like a builder block that builds the module's ClassMethods, so its defs belong to that module (#252). The defs in any other such block have their owner unknown.

Parameters:

  • node (Prism::CallNode) —

    call node.



284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
# File 'lib/mutineer/project.rb', line 284

def visit_call_node(node)
  if %i[public private protected].include?(node.name) && node.receiver.nil? && node.arguments.nil?
    @module_function_active = false # without arguments, Ruby goes back to instance methods
  end
  if node.name == :module_function && node.receiver.nil?
    args = node.arguments&.arguments || []
    if args.empty?
      @module_function_active = true
    elsif !@anonymous_block
      args.each do |arg|
        @module_function_names << [module_key, arg.value.to_sym] if arg.is_a?(Prism::SymbolNode)
        @module_function_names << [module_key, arg.name] if arg.is_a?(Prism::DefNode)
      end
    end
  end
  if node.name == :extend && (node.receiver.nil? || node.receiver.is_a?(Prism::SelfNode)) &&
     !@self_unknown && @singleton_depth.zero?
    args = node.arguments&.arguments || []
    concern = args.any? { |arg| arg.slice.delete_prefix("::") == "ActiveSupport::Concern" }
    @concern_modules << module_key if concern
  end
  case concern_block(node)
  when :owner_unknown
    hook = hook_block?(node)
    return preserving_scope do
      @hook_block ||= hook
      @hook_call, @hook_uses = placeable_hook(node) if hook
      @owner_unknown = true
      super
    end
  when :class_methods
    owner = named_owner((@block_namespace || @namespace_stack) + ["ClassMethods"])
    anonymous = false
  else
    return super unless builds_class?(node)

    anonymous = !@assigned&.first.equal?(node)
    owner = anonymous ? [nil, @namespace_stack, true] : @assigned.last
  end
  with_block_owner(owner, anonymous) do
    @self_scope = node.block
    super
  end
end

#visit_class_node(node) ⇒ void

This method returns an undefined value.

Visits class nodes and tracks namespace nesting.

Parameters:

  • node (Prism::ClassNode) —

    class node.



257
258
259
# File 'lib/mutineer/project.rb', line 257

def visit_class_node(node)
  with_namespace(node.constant_path) { super }
end

#visit_constant_write_node(node) ⇒ void Also known as: visit_constant_path_write_node, visit_constant_or_write_node, visit_constant_and_write_node, visit_constant_path_or_write_node, visit_constant_path_and_write_node

This method returns an undefined value.

Names the class a builder block assigned to this constant builds (see #builds_class?).

=, ||= and &&= store the class, so each names it; += stores what + returns, so its builder is left unnamed.

Parameters:

  • node (Prism::ConstantWriteNode, Prism::ConstantPathWriteNode, Prism::ConstantOrWriteNode, Prism::ConstantAndWriteNode, Prism::ConstantPathOrWriteNode, Prism::ConstantPathAndWriteNode) —

    constant assignment.



355
356
357
358
359
360
361
362
363
364
365
366
# File 'lib/mutineer/project.rb', line 355

def visit_constant_write_node(node)
  call = assigned_value(node.value)
  return super unless builds_class?(call)

  saved = @assigned
  @assigned = [call, assigned_owner(node)]
  begin
    super
  ensure
    @assigned = saved
  end
end

#visit_def_node(node) ⇒ void

This method returns an undefined value.

Records a discovered method definition.

Parameters:

  • node (Prism::DefNode) —

    method definition node.



398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
# File 'lib/mutineer/project.rb', line 398

def visit_def_node(node)
  subject = Subject.new(
    file: @file,
    namespace: (@block_namespace || @namespace_stack).dup,
    lexical: @lexical_stack.dup,
    block_owner: @block_owner,
    owner_unknown: @owner_unknown,
    hook_block: @hook_block,
    reload_hook_call: reload_hook_call_for(node),
    name: node.name,
    singleton: !node.receiver.nil? || @singleton_depth.positive? || @module_function_active,
    def_node: node,
    enclosing_subject: @enclosing_subject
  )
  @subjects << subject
  @subject_keys << module_key
  saved_active = @module_function_active
  saved_self = [@self_unknown, @self_scope, @enclosing_subject]
  @self_unknown = true # `self` in a method body is the receiver it is called on
  @self_scope = node
  @enclosing_subject = subject
  super
  @module_function_active = saved_active # a visibility call in a method body runs only when it is called
  @self_unknown, @self_scope, @enclosing_subject = saved_self
end

#visit_module_node(node) ⇒ void

This method returns an undefined value.

Visits module nodes and tracks namespace nesting.

Parameters:

  • node (Prism::ModuleNode) —

    module node.



265
266
267
# File 'lib/mutineer/project.rb', line 265

def visit_module_node(node)
  with_namespace(node.constant_path) { super }
end

#visit_singleton_class_node(node) ⇒ void

This method returns an undefined value.

Methods inside class << self are class methods of the enclosing namespace, but their def nodes have no receiver — track the singleton context so they're recorded as singleton (so redefine targets the singleton_class, not instances). class << some_other_obj can't be represented against the namespace, so its defs are skipped (not recursed).

Parameters:

  • node (Prism::SingletonClassNode) —

    singleton-class node.



381
382
383
384
385
386
387
388
389
390
391
392
# File 'lib/mutineer/project.rb', line 381

def visit_singleton_class_node(node)
  return unless node.expression.is_a?(Prism::SelfNode)

  @singleton_depth += 1
  saved_active = @module_function_active
  saved_uncertain = @singleton_uncertain
  @singleton_uncertain ||= @self_unknown # `self` here may be another object (#216)
  super
  @module_function_active = saved_active # a visibility call in here is not the module body's
  @singleton_uncertain = saved_uncertain
  @singleton_depth -= 1
end

#with_block_owner(owner, anonymous) { ... } ⇒ void (private)

This method returns an undefined value.

Runs the block with the defs it visits owned by the class a builder block builds. The block body defines instance methods of that class, even inside class << self, but its constants still land where the enclosing class << self puts them.

Parameters:

  • owner (Array(String, Array<String>, Boolean)) —

    the owner as written, its namespace, and whether that name is unknown.

  • anonymous (Boolean) —

    true when the block is not assigned to a constant.

Yields:

  • the builder call visit.



748
749
750
751
752
753
754
755
756
757
758
759
# File 'lib/mutineer/project.rb', line 748

def with_block_owner(owner, anonymous)
  preserving_scope do
    @singleton_cref = singleton_name if @singleton_depth.positive?
    @block_owner, @block_namespace, @owner_unknown = owner
    @anonymous_block = anonymous
    @self_unknown = @singleton_uncertain = false
    @module_function_active = false
    @singleton_depth = 0
    @body = Object.new
    yield
  end
end

#with_namespace(path) { ... } ⇒ void (private)

This method returns an undefined value.

Runs the block with path pushed as the current namespace. A root-anchored path (module ::X / class ::X) names the top-level X, not X nested in the enclosing scope, so the namespace restarts there. Bareword module_function state does not cross a class or module boundary: each body starts without it, and the outer state returns after. A class or module X opened inside class << self, even within a builder block there, is a constant of the singleton class, which has no constant path. It and everything nested in it is named under #<Class:...> with its owner unknown (#208), and its body defines instance methods again. A compact Foo::X or a top-level ::X there is named as written, and its owner is unknown too: redefine reopens the lexical chain without the singleton class, so constants the body looks up through it would not resolve. A self::X in any block is under the block's self, not the namespace around the block (#229). In a builder block that is the built class, so it is named under the builder's constant; in any other block (class_eval, a callback) self may be any object, so it is named under the innermost enclosing builder's constant, or else the enclosing namespace. Either way the last segment is a WrittenName, and it and everything nested in it has its owner unknown. Redefine reopens the lexical chain (module Outer; module X), which never reaches the block's self; reopening X through its constant with class_eval, as for self::X = ... in a builder block, would drop X from Module.nesting, so constants its body looks up would not resolve.

Parameters:

  • path (Prism::Node) —

    the class/module constant path.

Yields:

  • the class or module body visit.



492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
# File 'lib/mutineer/project.rb', line 492

def with_namespace(path)
  preserving_scope do
    name = extract_constant_name(path)
    root = root_anchored?(path)
    in_singleton = !@singleton_cref.nil? || @singleton_depth.positive?
    self_in_block = !in_singleton && !root && self_rooted?(path) && (!@block_namespace.nil? || @self_unknown)
    @namespace_stack =
      if root then [name]
      elsif in_singleton then path.is_a?(Prism::ConstantPathNode) ? [path.slice] : [singleton_name, name]
      elsif self_in_block then (@block_namespace || @namespace_stack) + [WrittenName.new(name, @self_scope)]
      else @namespace_stack + [name]
      end
    @lexical_stack += [root ? "::#{name}" : name]
    @module_function_active = false
    @block_owner = @block_namespace = @hook_call = nil
    # redefine reopens the lexical chain, which does not pass through the block's `self`
    @namespace_unknown = @owner_unknown = in_singleton || self_in_block || @namespace_unknown
    @singleton_depth = 0
    @singleton_cref = nil
    @anonymous_block = @self_unknown = @singleton_uncertain = false
    @body = Object.new
    yield
  end
end

#written?(namespace) ⇒ Boolean (private)

True when any segment of the namespace is a WrittenName.

Parameters:

  • namespace (Array<String>) —

    namespace segments.

Returns:

  • (Boolean)


451
452
453
# File 'lib/mutineer/project.rb', line 451

def written?(namespace)
  namespace.any?(WrittenName)
end