jazzy 0.13.4 → 0.14.0

data/lib/jazzy/stats.rb

@@ -1,10 +1,11 @@
+# frozen_string_literal: true
+
 module Jazzy
   # Collect + report metadata about a processed module
   class Stats
     include Config::Mixin
 
-    attr_reader :documented, :acl_skipped
-    attr_reader :undocumented_decls
+    attr_reader :documented, :acl_skipped, :undocumented_decls
 
     def add_documented
       @documented += 1
@@ -57,6 +58,7 @@ module Jazzy
 
     def doc_coverage
       return 0 if acl_included == 0
+
       (100 * documented) / acl_included
     end
 

data/lib/jazzy/symbol_graph.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require 'set'
+require 'jazzy/symbol_graph/graph'
+require 'jazzy/symbol_graph/constraint'
+require 'jazzy/symbol_graph/symbol'
+require 'jazzy/symbol_graph/relationship'
+require 'jazzy/symbol_graph/sym_node'
+require 'jazzy/symbol_graph/ext_node'
+
+# This is the top-level symbolgraph driver that deals with
+# figuring out arguments, running the tool, and loading the
+# results.
+
+module Jazzy
+  module SymbolGraph
+    # Run `swift symbolgraph-extract` with configured args,
+    # parse the results, and return as JSON in SourceKit[ten]
+    # format.
+    def self.build(config)
+      Dir.mktmpdir do |tmp_dir|
+        args = arguments(config, tmp_dir)
+
+        Executable.execute_command('swift',
+                                   args.unshift('symbolgraph-extract'),
+                                   true) # raise on error
+
+        Dir[tmp_dir + '/*.symbols.json'].map do |filename|
+          # The @ part is for extensions in our module (before the @)
+          # of types in another module (after the @).
+          filename =~ /(.*?)(@(.*?))?\.symbols/
+          module_name = Regexp.last_match[3] || Regexp.last_match[1]
+          {
+            filename =>
+              Graph.new(File.read(filename), module_name).to_sourcekit,
+          }
+        end.to_json
+      end
+    end
+
+    # Figure out the args to pass to symbolgraph-extract
+    def self.arguments(config, output_path)
+      if config.module_name.empty?
+        raise 'error: `--swift-build-tool symbolgraph` requires `--module`.'
+      end
+
+      user_args = config.build_tool_arguments.join
+
+      if user_args =~ /-(?:module-name|minimum-access-level|output-dir)/
+        raise 'error: `--build-tool-arguments` for '\
+          "`--swift-build-tool symbolgraph` can't use `-module`, "\
+          '`-minimum-access-level`, or `-output-dir`.'
+      end
+
+      # Default set
+      args = [
+        '-module-name', config.module_name,
+        '-minimum-access-level', 'private',
+        '-output-dir', output_path,
+        '-skip-synthesized-members'
+      ]
+
+      # Things user can override
+      args += ['-sdk', sdk(config)] unless user_args =~ /-sdk/
+      args += ['-target', target] unless user_args =~ /-target/
+      args += ['-F', config.source_directory.to_s] unless user_args =~ /-F(?!s)/
+      args += ['-I', config.source_directory.to_s] unless user_args =~ /-I/
+
+      args + config.build_tool_arguments
+    end
+
+    # Get the SDK path.  On !darwin this just isn't needed.
+    def self.sdk(config)
+      `xcrun --show-sdk-path --sdk #{config.sdk}`.chomp
+    end
+
+    # Guess a default LLVM target.  Feels like the tool should figure this
+    # out from sdk + the binary somehow?
+    def self.target
+      `swift -version` =~ /Target: (.*?)$/
+      Regexp.last_match[1] || 'x86_64-apple-macosx10.15'
+    end
+
+    # This is a last-ditch fallback for when symbolgraph doesn't
+    # provide a name - at least conforming external types to local
+    # protocols.
+    def self.demangle(usr)
+      args = %w[demangle -simplified -compact].append(usr.sub(/^s:/, 's'))
+      output, = Executable.execute_command('swift', args, true)
+      output.chomp
+    rescue StandardError
+      usr
+    end
+  end
+end

data/lib/jazzy/symbol_graph/constraint.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Jazzy
+  module SymbolGraph
+    # Constraint is a tidied-up JSON object, used by both Symbol and
+    # Relationship, and key to reconstructing extensions.
+    class Constraint
+      attr_accessor :kind
+      attr_accessor :lhs
+      attr_accessor :rhs
+
+      private
+
+      def initialize(kind, lhs, rhs)
+        self.kind = kind # "==" or ":"
+        self.lhs = lhs
+        self.rhs = rhs
+      end
+
+      public
+
+      KIND_MAP = {
+        'conformance' => ':',
+        'superclass' => ':',
+        'sameType' => '==',
+      }.freeze
+
+      # Init from a JSON hash
+      def self.new_hash(hash)
+        kind = KIND_MAP[hash[:kind]]
+        raise "Unknown constraint kind '#{kind}'" unless kind
+
+        lhs = hash[:lhs].sub(/^Self\./, '')
+        rhs = hash[:rhs].sub(/^Self\./, '')
+        new(kind, lhs, rhs)
+      end
+
+      # Init from a Swift declaration fragment eg. 'A : B'
+      def self.new_declaration(decl)
+        decl =~ /^(.*?)\s*([:<=]+)\s*(.*)$/
+        new(Regexp.last_match[2],
+            Regexp.last_match[1],
+            Regexp.last_match[3])
+      end
+
+      def to_swift
+        "#{lhs} #{kind} #{rhs}"
+      end
+
+      # The first component of types in the constraint
+      def type_names
+        Set.new([lhs, rhs].map { |n| n.sub(/\..*$/, '') })
+      end
+
+      def self.new_list(hash_list)
+        hash_list.map { |h| Constraint.new_hash(h) }.sort.uniq
+      end
+
+      # Swift protocols and reqs have an implementation/hidden conformance
+      # to their own protocol: we don't want to think about this in docs.
+      def self.new_list_for_symbol(hash_list, path_components)
+        hash_list.map do |hash|
+          if hash[:lhs] == 'Self' &&
+             hash[:kind] == 'conformance' &&
+             path_components.include?(hash[:rhs])
+            next nil
+          end
+
+          Constraint.new_hash(hash)
+        end.compact
+      end
+
+      # Workaround Swift 5.3 bug with missing constraint rels
+      def self.new_list_from_declaration(decl)
+        decl.split(/\s*,\s*/).map { |cons| Constraint.new_declaration(cons) }
+      end
+
+      # Sort order - by Swift text
+      include Comparable
+
+      def <=>(other)
+        to_swift <=> other.to_swift
+      end
+
+      alias eql? ==
+
+      def hash
+        to_swift.hash
+      end
+    end
+  end
+end
+
+class Array
+  def to_where_clause
+    empty? ? '' : " where #{map(&:to_swift).join(', ')}"
+  end
+end

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,195 @@
+# 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.
+      def redundant_conformance?(rel, type, protocol)
+        type && rel.constraints.empty? && type.conformance?(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