jazzy 0.13.5 → 0.14.1

data/lib/jazzy/symbol_graph/ext_node.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Jazzy
+  module SymbolGraph
+    # For extensions we need to track constraints of the extended type
+    # and the constraints introduced by the extension.
+    class ExtConstraints
+      attr_accessor :type # array
+      attr_accessor :ext # array
+
+      # all constraints inherited by members of the extension
+      def merged
+        (type + ext).sort
+      end
+
+      def initialize(type_constraints, ext_constraints)
+        self.type = type_constraints || []
+        self.ext = ext_constraints || []
+      end
+    end
+
+    # An ExtNode is a node of the reconstructed syntax tree representing
+    # an extension that we fabricate to resolve certain relationships.
+    class ExtNode < BaseNode
+      attr_accessor :usr
+      attr_accessor :name
+      attr_accessor :all_constraints # ExtConstraints
+      attr_accessor :conformances # array, can be empty
+
+      # Deduce an extension from a member of an unknown type or
+      # of known type with additional constraints
+      def self.new_for_member(type_usr,
+                              member,
+                              constraints)
+        new(type_usr,
+            member.parent_qualified_name,
+            constraints).tap { |o| o.add_child(member) }
+      end
+
+      # Deduce an extension from a protocol conformance for some type
+      def self.new_for_conformance(type_usr,
+                                   type_name,
+                                   protocol,
+                                   constraints)
+        new(type_usr, type_name, constraints).tap do |o|
+          o.add_conformance(protocol)
+        end
+      end
+
+      private
+
+      def initialize(usr, name, constraints)
+        self.usr = usr
+        self.name = name
+        self.all_constraints = constraints
+        self.conformances = []
+        super()
+      end
+
+      public
+
+      def constraints
+        all_constraints.merged
+      end
+
+      def add_conformance(protocol)
+        conformances.append(protocol).sort!
+      end
+
+      def full_declaration
+        decl = "extension #{name}"
+        unless conformances.empty?
+          decl += " : #{conformances.join(', ')}"
+        end
+        decl + all_constraints.ext.to_where_clause
+      end
+
+      def to_sourcekit(module_name)
+        declaration = full_declaration
+        xml_declaration = "<swift>#{CGI.escapeHTML(declaration)}</swift>"
+
+        hash = {
+          'key.kind' => 'source.lang.swift.decl.extension',
+          'key.usr' => usr,
+          'key.name' => name,
+          'key.modulename' => module_name,
+          'key.parsed_declaration' => declaration,
+          'key.annotated_decl' => xml_declaration,
+        }
+
+        unless conformances.empty?
+          hash['key.inheritedtypes'] = conformances.map do |conformance|
+            { 'key.name' => conformance }
+          end
+        end
+
+        unless children.empty?
+          hash['key.substructure'] = children_to_sourcekit
+        end
+
+        hash
+      end
+
+      # Sort order - by type name then constraint
+      include Comparable
+
+      def sort_key
+        name + constraints.map(&:to_swift).join
+      end
+
+      def <=>(other)
+        sort_key <=> other.sort_key
+      end
+    end
+  end
+end

data/lib/jazzy/symbol_graph/graph.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ClassLength
+module Jazzy
+  module SymbolGraph
+    # A Graph is the coordinator to import a symbolgraph json file.
+    # Deserialize it to Symbols and Relationships, then rebuild
+    # the AST shape using SymNodes and ExtNodes and extract SourceKit json.
+    class Graph
+      attr_accessor :module_name
+      attr_accessor :symbol_nodes # usr -> SymNode
+      attr_accessor :relationships # [Relationship]
+      attr_accessor :ext_nodes # (usr, constraints) -> ExtNode
+
+      # Parse the JSON into flat tables of data
+      def initialize(json, module_name)
+        self.module_name = module_name
+        graph = JSON.parse(json, symbolize_names: true)
+
+        self.symbol_nodes = {}
+        graph[:symbols].each do |hash|
+          symbol = Symbol.new(hash)
+          symbol_nodes[symbol.usr] = SymNode.new(symbol)
+        end
+
+        self.relationships =
+          graph[:relationships].map { |hash| Relationship.new(hash) }
+
+        self.ext_nodes = {}
+      end
+
+      # ExtNode index.  (type USR, extension constraints) -> ExtNode.
+      # This minimizes the number of extensions
+
+      def ext_key(usr, constraints)
+        usr + constraints.map(&:to_swift).join
+      end
+
+      def add_ext_member(type_usr, member_node, constraints)
+        key = ext_key(type_usr, constraints.ext)
+        if ext_node = ext_nodes[key]
+          ext_node.add_child(member_node)
+        else
+          ext_nodes[key] =
+            ExtNode.new_for_member(type_usr, member_node, constraints)
+        end
+      end
+
+      def add_ext_conformance(type_usr,
+                              type_name,
+                              protocol,
+                              constraints)
+        key = ext_key(type_usr, constraints.ext)
+        if ext_node = ext_nodes[key]
+          ext_node.add_conformance(protocol)
+        else
+          ext_nodes[key] =
+            ExtNode.new_for_conformance(type_usr,
+                                        type_name,
+                                        protocol,
+                                        constraints)
+        end
+      end
+
+      # Increasingly desparate ways to find the name of the symbol
+      # at the target end of a relationship
+      def rel_target_name(rel, target_node)
+        target_node&.symbol&.name ||
+          rel.target_fallback ||
+          Jazzy::SymbolGraph.demangle(rel.target_usr)
+      end
+
+      # Same for the source end.  Less help from the tool here
+      def rel_source_name(rel, source_node)
+        source_node&.qualified_name ||
+          Jazzy::SymbolGraph.demangle(rel.source_usr)
+      end
+
+      # Protocol conformance is redundant if it's unconditional
+      # and already expressed in the type's declaration.
+      #
+      # Skip implementation-detail conformances.
+      def redundant_conformance?(rel, type, protocol)
+        return false unless type
+
+        (rel.constraints.empty? && type.conformance?(protocol)) ||
+          (type.actor? && rel.actor_protocol?)
+      end
+
+      # source is a member/protocol requirement of target
+      def rebuild_member(rel, source, target)
+        return unless source
+
+        source.protocol_requirement = rel.protocol_requirement?
+        constraints =
+          ExtConstraints.new(target&.constraints,
+                             source.unique_context_constraints(target))
+
+        # Add to its parent or invent an extension
+        unless target&.try_add_child(source, constraints.ext)
+          add_ext_member(rel.target_usr, source, constraints)
+        end
+      end
+
+      # "source : target" either from type decl or ext decl
+      def rebuild_conformance(rel, source, target)
+        protocol_name = rel_target_name(rel, target)
+
+        return if redundant_conformance?(rel, source, protocol_name)
+
+        type_constraints = source&.constraints || []
+        constraints =
+          ExtConstraints.new(type_constraints,
+                             rel.constraints - type_constraints)
+
+        # Create an extension or enhance an existing one
+        add_ext_conformance(rel.source_usr,
+                            rel_source_name(rel, source),
+                            protocol_name,
+                            constraints)
+      end
+
+      # "source is a default implementation of protocol requirement target"
+      def rebuild_default_implementation(_rel, source, target)
+        return unless source
+
+        unless target &&
+               (target_parent = target.parent) &&
+               target_parent.is_a?(SymNode)
+          # Could probably figure this out with demangle, but...
+          warn "Can't resolve membership of default implementation "\
+            "#{source.symbol.usr}."
+          source.unlisted = true
+          return
+        end
+        constraints =
+          ExtConstraints.new(target_parent.constraints,
+                             source.unique_context_constraints(target_parent))
+
+        add_ext_member(target_parent.symbol.usr,
+                       source,
+                       constraints)
+      end
+
+      # "source is a class that inherits from target"
+      def rebuild_inherits(_rel, source, target)
+        if source && target
+          source.superclass_name = target.symbol.name
+        end
+      end
+
+      # Process a structural relationship to link nodes
+      def rebuild_rel(rel)
+        source = symbol_nodes[rel.source_usr]
+        target = symbol_nodes[rel.target_usr]
+
+        case rel.kind
+        when :memberOf, :optionalRequirementOf, :requirementOf
+          rebuild_member(rel, source, target)
+
+        when :conformsTo
+          rebuild_conformance(rel, source, target)
+
+        when :defaultImplementationOf
+          rebuild_default_implementation(rel, source, target)
+
+        when :inheritsFrom
+          rebuild_inherits(rel, source, target)
+        end
+        # don't seem to care about:
+        # - overrides: not bothered, also unimplemented for protocols
+      end
+
+      # Rebuild the AST structure  and convert to SourceKit
+      def to_sourcekit
+        # Do default impls after the others so we can find protocol
+        # type nodes from protocol requirements.
+        default_impls, other_rels =
+          relationships.partition(&:default_implementation?)
+        (other_rels + default_impls).each { |r| rebuild_rel(r) }
+
+        root_symbol_nodes =
+          symbol_nodes.values
+            .select(&:top_level_decl?)
+            .sort
+            .map(&:to_sourcekit)
+
+        root_ext_nodes =
+          ext_nodes.values
+            .sort
+            .map { |n| n.to_sourcekit(module_name) }
+        {
+          'key.diagnostic_stage' => 'parse',
+          'key.substructure' => root_symbol_nodes + root_ext_nodes,
+        }
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength

data/lib/jazzy/symbol_graph/relationship.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module Jazzy
+  module SymbolGraph
+    # A Relationship is a tidied-up SymbolGraph JSON object
+    class Relationship
+      attr_accessor :kind
+      attr_accessor :source_usr
+      attr_accessor :target_usr
+      attr_accessor :target_fallback # can be nil
+      attr_accessor :constraints # array, can be empty
+
+      KINDS = %w[memberOf conformsTo defaultImplementationOf
+                 overrides inheritsFrom requirementOf
+                 optionalRequirementOf].freeze
+
+      def protocol_requirement?
+        %i[requirementOf optionalRequirementOf].include? kind
+      end
+
+      def default_implementation?
+        kind == :defaultImplementationOf
+      end
+
+      # Protocol conformances added by compiler to actor decls that
+      # users aren't interested in.
+      def actor_protocol?
+        %w[Actor Sendable].include?(target_fallback)
+      end
+
+      def initialize(hash)
+        kind = hash[:kind]
+        unless KINDS.include?(kind)
+          raise "Unknown relationship kind '#{kind}'"
+        end
+
+        self.kind = kind.to_sym
+        self.source_usr = hash[:source]
+        self.target_usr = hash[:target]
+        if fallback = hash[:targetFallback]
+          # Strip the leading module name
+          self.target_fallback = fallback.sub(/^.*?\./, '')
+        end
+        self.constraints = Constraint.new_list(hash[:swiftConstraints] || [])
+      end
+    end
+  end
+end

data/lib/jazzy/symbol_graph/sym_node.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Jazzy
+  module SymbolGraph
+    # The rebuilt syntax tree is made of nodes that either match
+    # symbols or that we fabricate for extensions.  This is the common
+    # treeishness.
+    class BaseNode
+      attr_accessor :children # array, can be empty
+      attr_accessor :parent # can be nil
+
+      def initialize
+        self.children = []
+      end
+
+      def add_child(child)
+        child.parent = self
+        children.append(child)
+      end
+
+      def children_to_sourcekit
+        children.sort.map(&:to_sourcekit)
+      end
+    end
+
+    # A SymNode is a node of the reconstructed syntax tree holding a symbol.
+    # It can turn itself into SourceKit and helps decode extensions.
+    # rubocop:disable Metrics/ClassLength
+    class SymNode < BaseNode
+      attr_accessor :symbol
+      attr_writer :override
+      attr_writer :protocol_requirement
+      attr_writer :unlisted
+      attr_accessor :superclass_name
+
+      def override?
+        @override
+      end
+
+      def protocol_requirement?
+        @protocol_requirement
+      end
+
+      def top_level_decl?
+        !@unlisted && parent.nil?
+      end
+
+      def initialize(symbol)
+        self.symbol = symbol
+        super()
+      end
+
+      def qualified_name
+        symbol.path_components.join('.')
+      end
+
+      def parent_qualified_name
+        symbol.path_components[0...-1].join('.')
+      end
+
+      def protocol?
+        symbol.kind.end_with?('protocol')
+      end
+
+      def actor?
+        symbol.kind.end_with?('actor')
+      end
+
+      def constraints
+        symbol.constraints
+      end
+
+      # Add another SymNode as a member if possible.
+      # It must go in an extension if either:
+      #  - it has different generic constraints to us; or
+      #  - we're a protocol and it's a default impl / ext method
+      def try_add_child(node, unique_context_constraints)
+        unless unique_context_constraints.empty? &&
+               (!protocol? || node.protocol_requirement?)
+          return false
+        end
+
+        add_child(node)
+        true
+      end
+
+      # The `Constraint`s on this decl that are both:
+      # 1. Unique, ie. not just inherited from its context; and
+      # 2. Constraining the *context's* gen params rather than our own.
+      def unique_context_constraints(context)
+        return symbol.constraints unless context
+
+        new_generic_type_params =
+          symbol.generic_type_params - context.symbol.generic_type_params
+
+        (symbol.constraints - context.symbol.constraints)
+          .select { |con| con.type_names.disjoint?(new_generic_type_params) }
+      end
+
+      # Messy check whether we need to fabricate an extension for a protocol
+      # conformance: don't bother if it's already in the type declaration.
+      def conformance?(protocol)
+        return false unless symbol.declaration =~ /(?<=:).*?(?=(where|$))/
+
+        Regexp.last_match[0] =~ /\b#{protocol}\b/
+      end
+
+      # Generate the 'where' clause for the declaration
+      def where_clause
+        parent_constraints = parent&.constraints || []
+        (constraints - parent_constraints).to_where_clause
+      end
+
+      def inherits_clause
+        return '' unless superclass_name
+
+        " : #{superclass_name}"
+      end
+
+      # approximately...
+      def async?
+        symbol.declaration =~ /\basync\b[^)]*$/
+      end
+
+      def full_declaration
+        symbol.attributes
+          .append(symbol.declaration + inherits_clause + where_clause)
+          .join("\n")
+      end
+
+      # rubocop:disable Metrics/MethodLength
+      def to_sourcekit
+        declaration = full_declaration
+        xml_declaration = "<swift>#{CGI.escapeHTML(declaration)}</swift>"
+
+        hash = {
+          'key.kind' => symbol.kind,
+          'key.usr' => symbol.usr,
+          'key.name' => symbol.name,
+          'key.accessibility' => symbol.acl,
+          'key.parsed_decl' => declaration,
+          'key.annotated_decl' => xml_declaration,
+          'key.symgraph_async' => async?,
+        }
+        if docs = symbol.doc_comments
+          hash['key.doc.comment'] = docs
+          hash['key.doc.full_as_xml'] = ''
+        end
+        if params = symbol.parameter_names
+          hash['key.doc.parameters'] =
+            params.map { |name| { 'name' => name } }
+        end
+        if location = symbol.location
+          hash['key.filepath'] = location[:filename]
+          hash['key.doc.line'] = location[:line] + 1
+          hash['key.doc.column'] = location[:character] + 1
+        end
+        unless children.empty?
+          hash['key.substructure'] = children_to_sourcekit
+        end
+        hash['key.symgraph_spi'] = true if symbol.spi
+
+        hash
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Sort order - by symbol
+      include Comparable
+
+      def <=>(other)
+        symbol <=> other.symbol
+      end
+    end
+    # rubocop:enable Metrics/ClassLength
+  end
+end