necropsy 0.1.0 → 0.3.0

data/lib/necropsy/ast_scanner/ruby_semantics.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+module Necropsy
+  class AstScanner
+    private
+
+    def classify_receiver(receiver, context)
+      return { kind: :implicit, name: context.owner, candidates: [context.owner].compact } unless receiver
+      return { kind: :self, name: context.owner, candidates: [context.owner].compact } if receiver.is_a?(Prism::SelfNode)
+
+      constant = constant_name(receiver)
+      if constant
+        candidates = constant_candidates(constant, context.lexical_nesting)
+        return { kind: :constant, name: resolve_candidate_group(candidates), candidates: candidates }
+      end
+
+      if receiver.is_a?(Prism::CallNode) && receiver.name == :new
+        receiver_constant = constant_name(receiver.receiver)
+        if receiver_constant
+          candidates = constant_candidates(receiver_constant, context.lexical_nesting)
+          return { kind: :instance, name: resolve_candidate_group(candidates), candidates: candidates }
+        end
+      end
+
+      { kind: :unknown, name: nil, candidates: [] }
+    end
+
+    def first_symbol_argument(node)
+      symbol_arguments(node).first
+    end
+
+    def first_string_argument(node)
+      arguments(node).find { |argument| argument.is_a?(Prism::StringNode) }&.unescaped
+    end
+
+    def literal_argument(node, index:)
+      argument = arguments(node)[index]
+      return unless literal_name?(argument)
+
+      argument.unescaped.to_s
+    end
+
+    def literal_name?(node)
+      node.is_a?(Prism::SymbolNode) || node.is_a?(Prism::StringNode)
+    end
+
+    def symbol_arguments(node)
+      arguments(node).filter_map do |arg|
+        next unless arg.is_a?(Prism::SymbolNode)
+
+        arg.unescaped.to_s
+      end
+    end
+
+    def arguments(node)
+      node.arguments&.arguments || []
+    end
+
+    def keyword_value(node, key)
+      hash = arguments(node).find { |argument| argument.is_a?(Prism::KeywordHashNode) }
+      pair = hash&.elements&.find do |element|
+        element.is_a?(Prism::AssocNode) && literal_value(element.key).to_s == key
+      end
+      literal_value(pair&.value)
+    end
+
+    def keyword_keys(node)
+      hash = arguments(node).find { |argument| argument.is_a?(Prism::KeywordHashNode) }
+      Array(hash&.elements).filter_map do |element|
+        literal_value(element.key).to_s if element.is_a?(Prism::AssocNode)
+      end
+    end
+
+    def literal_value(node)
+      case node
+      when Prism::SymbolNode, Prism::StringNode
+        node.unescaped.to_s
+      when Prism::TrueNode
+        true
+      when Prism::FalseNode
+        false
+      end
+    end
+
+    def method_signature(parameters)
+      return { 'complete' => false } unless parameters
+
+      forwarding = parameters.child_nodes.compact.any? { |parameter| parameter.type == :forwarding_parameter_node }
+      keywords = Array(parameters.keywords)
+      keyword_rest = parameters.keyword_rest
+      no_keywords = !keyword_rest.nil? && keyword_rest.type == :no_keywords_parameter_node
+      accepts_keywords = keywords.any? || (!keyword_rest.nil? && !no_keywords)
+      {
+        'complete' => !forwarding,
+        'minimum_positionals' => Array(parameters.requireds).length + Array(parameters.posts).length,
+        'maximum_positionals' => if parameters.rest
+                                   nil
+                                 else
+                                   Array(parameters.requireds).length +
+                                     Array(parameters.optionals).length + Array(parameters.posts).length
+                                 end,
+        'required_keywords' => keywords.select do |parameter|
+          parameter.type == :required_keyword_parameter_node
+        end.map { |parameter| parameter.name.to_s }.sort,
+        'accepted_keywords' => keywords.map { |parameter| parameter.name.to_s }.sort,
+        'accepts_keywords' => accepts_keywords,
+        'no_keywords' => no_keywords,
+        'keyword_rest' => !keyword_rest.nil? && !no_keywords
+      }
+    end
+
+    def call_arguments(node, offset: 0)
+      values = Array(node.arguments&.arguments).drop(offset)
+      keyword_hash = values.find { |argument| argument.is_a?(Prism::KeywordHashNode) }
+      positional = values.grep_v(Prism::KeywordHashNode)
+      keyword_elements = Array(keyword_hash&.elements)
+      {
+        'complete' => positional.none? do |argument|
+          %i[splat_node forwarding_arguments_node].include?(argument.type)
+        end && keyword_elements.none? { |element| element.type == :assoc_splat_node },
+        'positional_count' => positional.length,
+        'keywords' => keyword_elements.filter_map do |element|
+          literal_value(element.key).to_s if element.is_a?(Prism::AssocNode)
+        end.sort
+      }
+    end
+
+    def incomplete_arguments
+      { 'complete' => false, 'positional_count' => 0, 'keywords' => [] }
+    end
+
+    def constant_name(node)
+      return nil unless node
+
+      case node
+      when Prism::ConstantReadNode
+        node.name.to_s
+      when Prism::ConstantPathNode
+        prefix = node.parent ? constant_name(node.parent) : ''
+        [prefix, node.name.to_s].join('::')
+      end
+    end
+
+    def qualify_constant(name, namespace)
+      return nil unless name
+      return name.delete_prefix('::') if name.start_with?('::')
+      return name if namespace.nil? || namespace.empty? || name.include?('::')
+
+      "#{namespace}::#{name}"
+    end
+
+    def record_class_info(node, namespace, context)
+      return unless namespace
+
+      data = class_record(namespace)
+      data[:kind] = node.is_a?(Prism::ModuleNode) ? :module : :class
+      data[:file] = context.relative_file
+      data[:line] = node.location.start_line
+      return unless node.respond_to?(:superclass)
+
+      unless node.superclass
+        data[:superclass_candidates] = implicit_superclass_candidates(namespace)
+        return
+      end
+
+      superclass = constant_name(node.superclass)
+      if superclass
+        data[:superclass_candidates] = constant_candidates(superclass, context.lexical_nesting)
+        return
+      end
+
+      data[:superclass_candidates] = []
+      data[:dynamic] = true
+      record_semantic_blocker(
+        :dynamic_ancestry,
+        node.superclass,
+        context,
+        "#{namespace} has a runtime-computed superclass",
+        suggested_action: :make_superclass_static,
+        scope_owner: namespace
+      )
+    end
+
+    def implicit_superclass_candidates(namespace)
+      return [] if namespace == 'BasicObject'
+      return ['BasicObject'] if namespace == 'Object'
+
+      ['Object']
+    end
+
+    def class_record(namespace)
+      class_data[namespace] ||= {
+        id: namespace,
+        kind: :class,
+        file: nil,
+        line: nil,
+        superclass: nil,
+        superclass_candidates: [],
+        includes: [],
+        prepends: [],
+        extends: [],
+        singleton_includes: [],
+        singleton_prepends: [],
+        dynamic: false
+      }
+    end
+
+    def class_infos
+      class_data.values.map do |data|
+        superclass_candidates = data.fetch(:superclass_candidates)
+        ClassInfo.new(
+          id: data.fetch(:id),
+          kind: data.fetch(:kind),
+          file: data[:file],
+          line: data[:line],
+          superclass: resolve_candidate_group(superclass_candidates),
+          superclass_candidates: superclass_candidates,
+          includes: resolve_candidate_groups(data.fetch(:includes)),
+          prepends: resolve_candidate_groups(data.fetch(:prepends)),
+          extends: resolve_candidate_groups(data.fetch(:extends)),
+          singleton_includes: resolve_candidate_groups(data.fetch(:singleton_includes)),
+          singleton_prepends: resolve_candidate_groups(data.fetch(:singleton_prepends)),
+          dynamic: data.fetch(:dynamic)
+        )
+      end
+    end
+
+    def resolve_candidate_groups(groups)
+      Array(groups).filter_map { |group| resolve_candidate_group(Array(group)) }.uniq
+    end
+
+    def resolve_candidate_group(group)
+      group.find { |candidate| class_data.key?(candidate) } || group.first
+    end
+
+    def constant_candidates(name, lexical_nesting)
+      return [name.delete_prefix('::')] if name.start_with?('::')
+
+      nesting = Array(lexical_nesting).compact
+      return [name] if nesting.empty?
+
+      head, *rest = name.split('::')
+      suffix = rest.empty? ? '' : "::#{rest.join('::')}"
+      candidates = nesting.map { |namespace| "#{namespace}::#{head}#{suffix}" }
+      inherited_namespaces(nesting.first).each do |ancestor|
+        candidates << "#{ancestor}::#{head}#{suffix}"
+      end
+      candidates << name
+      candidates.uniq
+    end
+
+    def inherited_namespaces(namespace, seen = Set.new)
+      return [] unless namespace && seen.add?(namespace)
+
+      data = class_data[namespace]
+      return [] unless data
+
+      Array(data[:superclass_candidates]).flat_map do |superclass|
+        [superclass, *inherited_namespaces(superclass, seen)]
+      end.uniq
+    end
+  end
+end

data/lib/necropsy/ast_scanner/traversal.rb

@@ -0,0 +1,347 @@
+# frozen_string_literal: true
+
+module Necropsy
+  class AstScanner
+    private
+
+    def resolve_deferred_module_function_sources
+      deferred_module_functions.each do |copy_id, instance_id|
+        module_function_sources[copy_id] = nodes.filter_map do |definition|
+          definition.graph_id if definition.kind == :instance_method && definition.symbol_id == instance_id
+        end
+        signatures = module_function_sources.fetch(copy_id).filter_map { |source_id| method_signatures[source_id] }.uniq
+        method_signatures[copy_id] = signatures.first if signatures.one?
+      end
+    end
+
+    def copy_module_function_call_sites
+      copies = module_function_sources.flat_map do |copy_id, source_ids|
+        source_ids.flat_map do |source_id|
+          call_sites.select { |site| site.caller_id == source_id }.map do |site|
+            derived_call_site(
+              site, derivation: :module_function, caller_id: copy_id,
+                    metadata: { 'module_function' => true }
+            )
+          end
+        end
+      end
+      call_sites.concat(copies)
+    end
+
+    def scan_file(file)
+      relative = project.relative_path(file)
+      test = project.test_file?(file)
+      context = Context.new(
+        namespace: nil,
+        lexical_nesting: [],
+        owner: nil,
+        current_caller_id: nil,
+        current_method_name: nil,
+        current_kind: :block_entry,
+        root_id: nil,
+        file: file,
+        relative_file: relative,
+        test: test,
+        singleton_scope: false,
+        visibility: :public,
+        module_function: false,
+        static_ancestry: true,
+        flow_result: nil
+      )
+      result = Prism.parse(File.read(file))
+      root = add_definition(
+        symbol_id: "file:#{relative}",
+        kind: :block_entry,
+        source_node: result.value,
+        context: context,
+        defined_via: :file,
+        owner: nil,
+        name: relative,
+        visibility: :public
+      )
+      root_id = root.graph_id
+      context.current_caller_id = root_id
+      context.root_id = root_id
+
+      if result.failure?
+        file_statuses[relative] = :recovered
+        record_parse_errors(root_id, relative, result)
+      else
+        file_statuses[relative] = :complete
+      end
+
+      visit(result.value, context)
+    rescue DefinitionIdentity::CanonicalizationError, SystemStackError, SystemCallError, EncodingError => e
+      record_source_failure(root_id || "file:#{relative}", relative, e)
+    end
+
+    def visit(node, context)
+      return unless node.respond_to?(:child_nodes)
+
+      case node
+      when Prism::ClassNode, Prism::ModuleNode
+        visit_namespace(node, context)
+      when Prism::DefNode
+        visit_def(node, context)
+      when Prism::CallNode
+        visit_call(node, context)
+      when Prism::AliasMethodNode
+        visit_alias_method_node(node, context)
+      when Prism::SuperNode, Prism::ForwardingSuperNode
+        visit_super(node, context)
+      when Prism::SingletonClassNode
+        visit_singleton_class(node, context)
+      when Prism::ConstantWriteNode
+        visit_constant_write(node, context)
+      else
+        visit_generic_node(node, context)
+      end
+    end
+
+    def visit_generic_node(node, context)
+      return visit_children(node, context) unless ANCESTRY_CONTROL_FLOW_TYPES.include?(node.type)
+
+      nested_context = context.dup
+      nested_context.static_ancestry = false
+      visit_children(node, nested_context)
+    end
+
+    def visit_namespace(node, context)
+      namespace = qualify_constant(constant_name(node.constant_path), context.namespace)
+      record_class_info(node, namespace, context)
+      visit(node.superclass, context) if node.respond_to?(:superclass) && node.superclass
+      child_context = context.dup
+      child_context.namespace = namespace
+      child_context.lexical_nesting = [namespace, *context.lexical_nesting].compact.uniq
+      child_context.owner = namespace
+      child_context.singleton_scope = false
+      child_context.visibility = :public
+      child_context.module_function = false
+      visit(node.body, child_context)
+    end
+
+    def visit_def(node, context)
+      owner = definition_owner(node, context)
+      unless owner
+        visit(node.receiver, context) if node.receiver
+        record_semantic_blocker(
+          :dynamic_singleton_definition,
+          node,
+          context,
+          'singleton method receiver is not statically bounded',
+          suggested_action: :make_singleton_receiver_static,
+          force_global: true
+        )
+        visit_synthetic_body(node.body, context, :dynamic_singleton_method)
+        return
+      end
+
+      kind = node.receiver || context.singleton_scope ? :singleton_method : :instance_method
+      separator = kind == :singleton_method ? '.' : '#'
+      id = "#{owner}#{separator}#{node.name}"
+      definition = add_definition(
+        symbol_id: id,
+        kind: kind,
+        source_node: node,
+        context: context,
+        defined_via: :def,
+        owner: owner,
+        name: node.name.to_s,
+        visibility: node.receiver ? :public : context.visibility
+      )
+      method_signatures[definition.graph_id] = method_signature(node.parameters)
+      record_module_function_copy(node, context, definition) if kind == :instance_method && context.module_function
+      if %i[method_missing respond_to_missing?].include?(node.name)
+        uncertainties[definition.graph_id] << "#{owner} defines #{node.name}"
+        class_record(owner)[:dynamic] = true
+      end
+      rule_hit = convention_rules.method_hit(
+        owner: owner,
+        method_name: node.name,
+        ancestors: convention_ancestors(owner),
+        frameworks: project.config.frameworks
+      )
+      if rule_hit
+        entrypoint_hints << EntryPoint.new(
+          node_id: definition.graph_id,
+          reason: :convention_callback,
+          evidence: { 'type' => 'convention_rule', **rule_hit }
+        )
+      end
+
+      method_context = context.dup
+      method_context.owner = owner
+      method_context.current_caller_id = definition.graph_id
+      method_context.current_method_name = node.name.to_s
+      method_context.current_kind = kind
+      method_context.singleton_scope = false
+      method_context.visibility = :public
+      method_context.module_function = false
+      method_context.static_ancestry = false
+      method_context.flow_result = FlowInterpreter.new(
+        constant_resolver: lambda do |constant|
+          resolve_candidate_group(constant_candidates(constant, method_context.lexical_nesting))
+        end
+      ).analyze(node.body)
+      method_context.flow_result.issues.each do |issue|
+        uncertainties[definition.graph_id] << "Forward value analysis stopped at #{issue}; affected calls use conservative lookup"
+      end
+      visit_default_parameters(node.parameters, method_context)
+      visit(node.body, method_context)
+    end
+
+    def visit_default_parameters(parameters, context)
+      return unless parameters
+
+      defaults = [*Array(parameters.optionals), *Array(parameters.keywords)].filter_map do |parameter|
+        parameter.value if parameter.respond_to?(:value)
+      end
+      defaults.each { |default| visit(default, context) }
+    end
+
+    def convention_ancestors(owner)
+      ancestors = []
+      pending = convention_parent_candidates(class_data[owner])
+      until pending.empty?
+        current = pending.shift
+        next if ancestors.include?(current)
+
+        ancestors << current
+        pending.concat(convention_parent_candidates(class_data[current]))
+      end
+      ancestors
+    end
+
+    def convention_parent_candidates(data)
+      return [] unless data
+
+      Array(data[:superclass_candidates]) +
+        %i[includes prepends extends singleton_includes singleton_prepends].flat_map do |relation|
+          Array(data[relation]).flatten
+        end
+    end
+
+    def visit_call(node, context)
+      handlers = %i[
+        handle_unsupported_semantics handle_visibility handle_module_function handle_eval
+        handle_define_singleton_method handle_define_method handle_attr_macro handle_delegate
+        handle_forwardable handle_alias_method handle_method_removal
+      ]
+      handled = handlers.lazy.map { |handler| send(handler, node, context) }.find(&:itself)
+      if handled
+        raise TypeError, "semantic call handler must return AstScanner::CallTraversal, got #{handled.class}" unless
+          handled.is_a?(CallTraversal)
+
+        visit_call_children(
+          node,
+          context,
+          visit_receiver: handled.receiver,
+          visit_arguments: handled.arguments,
+          visit_block: handled.block
+        )
+        return
+      end
+
+      handle_module_relation(node, context)
+      callback_block_consumed = handle_rails_callback(node, context)
+      handle_graphql_field(node, context)
+      if handle_generated_rails_methods(node, context)
+        visit_call_children(node, context, visit_block: false)
+        return
+      end
+
+      record_instantiation(node, context)
+      record_symbol_reference(node, context)
+      record_symbol_to_proc(node, context)
+      sites = build_call_sites(node, context).compact
+      call_sites.concat(sites)
+      sites.each { |site| record_uncertainty(site) if site.dynamic }
+      record_uncertainty_at(node, context) if sites.empty? && unresolved_dynamic_dispatch?(node)
+
+      visit_call_children(node, context, visit_block: !callback_block_consumed)
+    end
+
+    def visit_call_children(node, context, visit_receiver: true, visit_arguments: true, visit_block: true)
+      visit(node.receiver, context) if visit_receiver && node.receiver
+      arguments(node).each { |argument| visit(argument, context) } if visit_arguments
+      visit(node.block, context) if visit_block && node.block
+    end
+
+    def visit_synthetic_body(body, context, purpose)
+      return unless body
+
+      synthetic = add_definition(
+        symbol_id: "synthetic:#{purpose}:#{context.relative_file}:#{body.location.start_line}",
+        kind: :block_entry,
+        source_node: body,
+        context: context,
+        defined_via: purpose,
+        owner: context.owner,
+        name: purpose,
+        visibility: :public
+      )
+      body_context = context.dup
+      body_context.current_caller_id = synthetic.graph_id
+      body_context.current_method_name = nil
+      body_context.current_kind = :block_entry
+      body_context.static_ancestry = false
+      body_context.flow_result = nil
+      visit(body, body_context)
+      synthetic
+    end
+
+    def visit_super(node, context)
+      method_name = context.current_method_name
+      if method_name
+        add_scanned_call_site(
+          source_node: node,
+          context: context,
+          role: :super,
+          message: method_name,
+          receiver_kind: :super,
+          receiver_name: context.owner,
+          dynamic: false,
+          metadata: {
+            'super' => true,
+            'zsuper' => node.is_a?(Prism::ForwardingSuperNode),
+            'arguments' => node.is_a?(Prism::ForwardingSuperNode) ? incomplete_arguments : call_arguments(node)
+          }
+        )
+      end
+      visit_children(node, context)
+    end
+
+    def visit_singleton_class(node, context)
+      owner = singleton_class_owner(node.expression, context)
+      unless owner
+        visit(node.expression, context)
+        record_semantic_blocker(
+          :dynamic_singleton_definition,
+          node,
+          context,
+          'singleton class receiver is not statically bounded',
+          suggested_action: :make_singleton_receiver_static,
+          force_global: true
+        )
+        return
+      end
+
+      singleton_context = context.dup
+      singleton_context.namespace = owner
+      singleton_context.owner = owner
+      singleton_context.singleton_scope = true
+      singleton_context.visibility = :public
+      singleton_context.module_function = false
+      visit(node.body, singleton_context)
+    end
+
+    def singleton_class_owner(expression, context)
+      return context.owner if expression.is_a?(Prism::SelfNode)
+
+      name = constant_name(expression)
+      return unless name
+
+      resolve_candidate_group(constant_candidates(name, context.lexical_nesting))
+    end
+  end
+end

data/lib/necropsy/ast_scanner/value_definitions.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Necropsy
+  class AstScanner
+    private
+
+    def visit_constant_write(node, context)
+      return visit_children(node, context) unless struct_or_data_definition?(node.value)
+
+      owner = qualify_constant(node.name.to_s, context.namespace)
+      data = class_record(owner)
+      data[:kind] = :class
+      data[:file] = context.relative_file
+      data[:line] = node.location.start_line
+      instantiated_classes << owner
+
+      value_arguments = arguments(node.value)
+      names = value_arguments.filter_map { |argument| literal_value(argument) if literal_name?(argument) }
+      if names.length != value_arguments.length
+        record_semantic_blocker(
+          :dynamic_generated_methods,
+          node.value,
+          context,
+          "#{node.value.name} has runtime-computed member names",
+          suggested_action: :make_member_name_literal,
+          scope_owner: owner
+        )
+      end
+
+      names.each do |name|
+        add_definition(
+          symbol_id: "#{owner}##{name}",
+          kind: :instance_method,
+          source_node: node,
+          context: context,
+          defined_via: node.value.name == :define ? :data_define : :struct_new,
+          owner: owner,
+          name: name,
+          visibility: :public
+        )
+        next if node.value.name == :define
+
+        add_definition(
+          symbol_id: "#{owner}##{name}=",
+          kind: :instance_method,
+          source_node: node,
+          context: context,
+          defined_via: :struct_new,
+          owner: owner,
+          name: "#{name}=",
+          visibility: :public
+        )
+      end
+
+      return unless node.value.block
+
+      block_context = context.dup
+      block_context.namespace = owner
+      block_context.owner = owner
+      block_context.singleton_scope = false
+      block_context.visibility = :public
+      block_context.module_function = false
+      block_context.static_ancestry = false
+      visit(node.value.block.body, block_context)
+    end
+
+    def struct_or_data_definition?(value)
+      return false unless value.is_a?(Prism::CallNode)
+
+      receiver_name = constant_name(value.receiver)
+      (receiver_name == 'Struct' && value.name == :new) || (receiver_name == 'Data' && value.name == :define)
+    end
+
+    def visit_children(node, context)
+      node.child_nodes.compact.each { |child| visit(child, context) }
+    end
+  end
+end