jazzy 0.13.5 → 0.14.1

data/lib/jazzy/symbol_graph/symbol.rb

@@ -0,0 +1,248 @@
+# frozen_string_literal: true
+
+# rubocop:disable Metrics/ClassLength
+module Jazzy
+  module SymbolGraph
+    # A Symbol is a tidied-up SymbolGraph JSON object
+    class Symbol
+      attr_accessor :usr
+      attr_accessor :path_components
+      attr_accessor :declaration
+      attr_accessor :kind
+      attr_accessor :acl
+      attr_accessor :spi
+      attr_accessor :location # can be nil, keys :filename :line :character
+      attr_accessor :constraints # array, can be empty
+      attr_accessor :doc_comments # can be nil
+      attr_accessor :attributes # array, can be empty
+      attr_accessor :generic_type_params # set, can be empty
+      attr_accessor :parameter_names # array, can be nil
+
+      def name
+        path_components[-1] || '??'
+      end
+
+      def initialize(hash)
+        self.usr = hash[:identifier][:precise]
+        self.path_components = hash[:pathComponents]
+        raw_decl, keywords = parse_decl_fragments(hash[:declarationFragments])
+        init_kind(hash[:kind][:identifier], keywords)
+        init_declaration(raw_decl)
+        if func_signature = hash[:functionSignature]
+          init_func_signature(func_signature)
+        end
+        init_acl(hash[:accessLevel])
+        self.spi = hash[:spi]
+        if location = hash[:location]
+          init_location(location)
+        end
+        init_constraints(hash, raw_decl)
+        if comments_hash = hash[:docComment]
+          init_doc_comments(comments_hash)
+        end
+        init_attributes(hash[:availability] || [])
+        init_generic_type_params(hash)
+      end
+
+      def parse_decl_fragments(fragments)
+        decl = ''
+        keywords = Set.new
+        fragments.each do |frag|
+          decl += frag[:spelling]
+          keywords.add(frag[:spelling]) if frag[:kind] == 'keyword'
+        end
+        [decl, keywords]
+      end
+
+      # Repair problems with SymbolGraph's declprinter
+
+      def init_declaration(raw_decl)
+        # Too much 'Self.TypeName'; omitted arg labels look odd;
+        # duplicated constraints; swift 5.3 vs. master workaround
+        self.declaration = raw_decl
+          .gsub(/\bSelf\./, '')
+          .gsub(/(?<=\(|, )_: /, '_ arg: ')
+          .gsub(/ where.*$/, '')
+        if kind == 'source.lang.swift.decl.class'
+          declaration.sub!(/\s*:.*$/, '')
+        end
+      end
+
+      # Remember pieces of methods for later markdown parsing
+
+      def init_func_signature(func_signature)
+        self.parameter_names =
+          (func_signature[:parameters] || []).map { |h| h[:name] }
+      end
+
+      # Mapping SymbolGraph's declkinds to SourceKit
+
+      KIND_MAP = {
+        'class' => 'class',
+        'struct' => 'struct',
+        'enum' => 'enum',
+        'enum.case' => 'enumelement', # intentional
+        'protocol' => 'protocol',
+        'init' => 'function.constructor',
+        'deinit' => 'function.destructor',
+        'func.op' => 'function.operator',
+        'type.method' => 'function.method.class',
+        'static.method' => 'function.method.static',
+        'method' => 'function.method.instance',
+        'func' => 'function.free',
+        'type.property' => 'var.class',
+        'static.property' => 'var.static',
+        'property' => 'var.instance',
+        'var' => 'var.global',
+        'subscript' => 'function.subscript',
+        'type.subscript' => 'function.subscript',
+        'static.subscript' => 'function.subscript',
+        'typealias' => 'typealias',
+        'associatedtype' => 'associatedtype',
+        'actor' => 'actor',
+      }.freeze
+
+      # We treat 'static var' differently to 'class var'
+      # We treat actors as first-class entities
+      def adjust_kind_for_declaration(kind, keywords)
+        if kind == 'swift.class' && keywords.member?('actor')
+          return 'swift.actor'
+        end
+        return kind unless keywords.member?('static')
+
+        kind.gsub(/type/, 'static')
+      end
+
+      def init_kind(kind, keywords)
+        adjusted = adjust_kind_for_declaration(kind, keywords)
+        sourcekit_kind = KIND_MAP[adjusted.sub('swift.', '')]
+        raise "Unknown symbol kind '#{kind}'" unless sourcekit_kind
+
+        self.kind = "source.lang.swift.decl.#{sourcekit_kind}"
+      end
+
+      # Mapping SymbolGraph's ACL to SourceKit
+
+      def init_acl(acl)
+        self.acl = "source.lang.swift.accessibility.#{acl}"
+      end
+
+      # Symbol location - only available for public+ decls
+
+      def init_location(loc_hash)
+        self.location = {}
+        location[:filename] = loc_hash[:uri].sub(%r{^file://}, '')
+        location[:line] = loc_hash[:position][:line]
+        location[:character] = loc_hash[:position][:character]
+      end
+
+      # Generic constraints: in one or both of two places.
+      # There can be duplicates; these are removed by `Constraint`.
+      def init_constraints(hash, raw_decl)
+        raw_constraints = %i[swiftGenerics swiftExtension].flat_map do |key|
+          next [] unless container = hash[key]
+
+          container[:constraints] || []
+        end
+
+        constraints =
+          Constraint.new_list_for_symbol(raw_constraints, path_components)
+        if raw_decl =~ / where (.*)$/
+          constraints +=
+            Constraint.new_list_from_declaration(Regexp.last_match[1])
+        end
+
+        self.constraints = constraints.sort.uniq
+      end
+
+      # Generic type params
+      def init_generic_type_params(hash)
+        self.generic_type_params = Set.new(
+          if (generics = hash[:swiftGenerics]) &&
+             (parameters = generics[:parameters])
+            parameters.map { |p| p[:name] }
+          else
+            []
+          end,
+        )
+      end
+
+      def init_doc_comments(comments_hash)
+        self.doc_comments = comments_hash[:lines]
+          .map { |l| l[:text] }
+          .join("\n")
+      end
+
+      # Availability
+      # Re-encode this as Swift.  Should really teach Jazzy about these,
+      # could maybe then do something smarter here.
+      def availability_attributes(avail_hash_list)
+        avail_hash_list.map do |avail|
+          str = '@available('
+          if avail[:isUnconditionallyDeprecated]
+            str += '*, deprecated'
+          elsif domain = avail[:domain]
+            str += domain
+            %i[introduced deprecated obsoleted].each do |event|
+              if version = avail[event]
+                str += ", #{event}: #{decode_version(version)}"
+              end
+            end
+          else
+            warn "Found confusing availability: #{avail}"
+            next nil
+          end
+
+          str += ", message: \"#{avail[:message]}\"" if avail[:message]
+          str += ", renamed: \"#{avail[:renamed]}\"" if avail[:renamed]
+
+          str + ')'
+        end.compact
+      end
+
+      def decode_version(hash)
+        str = hash[:major].to_s
+        str += ".#{hash[:minor]}" if hash[:minor]
+        str += ".#{hash[:patch]}" if hash[:patch]
+        str
+      end
+
+      def spi_attributes
+        spi ? ['@_spi(Unknown)'] : []
+      end
+
+      def init_attributes(avail_hash_list)
+        self.attributes =
+          availability_attributes(avail_hash_list) + spi_attributes
+      end
+
+      # Sort order
+      include Comparable
+
+      def <=>(other)
+        # Things with location: order by file/line/column
+        # (pls tell what wheel i am reinventing :/)
+        if location && other_loc = other.location
+          if location[:filename] == other_loc[:filename]
+            if location[:line] == other_loc[:line]
+              return location[:character] <=> other_loc[:character]
+            end
+
+            return location[:line] <=> other_loc[:line]
+          end
+          return location[:filename] <=> other_loc[:filename]
+        end
+
+        # Things with a location before things without a location
+        return +1 if location.nil? && other.location
+        return -1 if location && other.location.nil?
+
+        # Things without a location: by name and then USR
+        return usr <=> other.usr if name == other.name
+
+        name <=> other.name
+      end
+    end
+  end
+end
+# rubocop:enable Metrics/ClassLength

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/themes/apple/assets/css/highlight.css.scss

@@ -1,63 +1,67 @@
+/*! Jazzy - https://github.com/realm/jazzy
+ *  Copyright Realm Inc.
+ *  SPDX-License-Identifier: MIT
+ */
 /* Credit to https://gist.github.com/wataru420/2048287 */
 
 .highlight {
-  .c { color: #999988; font-style: italic } /* Comment */
-  .err { color: #a61717; background-color: #e3d2d2 } /* Error */
-  .k { color: #000000; font-weight: bold } /* Keyword */
-  .o { color: #000000; font-weight: bold } /* Operator */
-  .cm { color: #999988; font-style: italic } /* Comment.Multiline */
-  .cp { color: #999999; font-weight: bold } /* Comment.Preproc */
-  .c1 { color: #999988; font-style: italic } /* Comment.Single */
-  .cs { color: #999999; font-weight: bold; font-style: italic } /* Comment.Special */
-  .gd { color: #000000; background-color: #ffdddd } /* Generic.Deleted */
-  .gd .x { color: #000000; background-color: #ffaaaa } /* Generic.Deleted.Specific */
-  .ge { color: #000000; font-style: italic } /* Generic.Emph */
-  .gr { color: #aa0000 } /* Generic.Error */
-  .gh { color: #999999 } /* Generic.Heading */
-  .gi { color: #000000; background-color: #ddffdd } /* Generic.Inserted */
-  .gi .x { color: #000000; background-color: #aaffaa } /* Generic.Inserted.Specific */
-  .go { color: #888888 } /* Generic.Output */
-  .gp { color: #555555 } /* Generic.Prompt */
-  .gs { font-weight: bold } /* Generic.Strong */
-  .gu { color: #aaaaaa } /* Generic.Subheading */
-  .gt { color: #aa0000 } /* Generic.Traceback */
-  .kc { color: #000000; font-weight: bold } /* Keyword.Constant */
-  .kd { color: #000000; font-weight: bold } /* Keyword.Declaration */
-  .kp { color: #000000; font-weight: bold } /* Keyword.Pseudo */
-  .kr { color: #000000; font-weight: bold } /* Keyword.Reserved */
-  .kt { color: #445588; } /* Keyword.Type */
-  .m { color: #009999 } /* Literal.Number */
-  .s { color: #d14 } /* Literal.String */
-  .na { color: #008080 } /* Name.Attribute */
-  .nb { color: #0086B3 } /* Name.Builtin */
-  .nc { color: #445588; font-weight: bold } /* Name.Class */
-  .no { color: #008080 } /* Name.Constant */
-  .ni { color: #800080 } /* Name.Entity */
-  .ne { color: #990000; font-weight: bold } /* Name.Exception */
-  .nf { color: #990000; } /* Name.Function */
-  .nn { color: #555555 } /* Name.Namespace */
-  .nt { color: #000080 } /* Name.Tag */
-  .nv { color: #008080 } /* Name.Variable */
-  .ow { color: #000000; font-weight: bold } /* Operator.Word */
-  .w { color: #bbbbbb } /* Text.Whitespace */
-  .mf { color: #009999 } /* Literal.Number.Float */
-  .mh { color: #009999 } /* Literal.Number.Hex */
-  .mi { color: #009999 } /* Literal.Number.Integer */
-  .mo { color: #009999 } /* Literal.Number.Oct */
-  .sb { color: #d14 } /* Literal.String.Backtick */
-  .sc { color: #d14 } /* Literal.String.Char */
-  .sd { color: #d14 } /* Literal.String.Doc */
-  .s2 { color: #d14 } /* Literal.String.Double */
-  .se { color: #d14 } /* Literal.String.Escape */
-  .sh { color: #d14 } /* Literal.String.Heredoc */
-  .si { color: #d14 } /* Literal.String.Interpol */
-  .sx { color: #d14 } /* Literal.String.Other */
-  .sr { color: #009926 } /* Literal.String.Regex */
-  .s1 { color: #d14 } /* Literal.String.Single */
-  .ss { color: #990073 } /* Literal.String.Symbol */
-  .bp { color: #999999 } /* Name.Builtin.Pseudo */
-  .vc { color: #008080 } /* Name.Variable.Class */
-  .vg { color: #008080 } /* Name.Variable.Global */
-  .vi { color: #008080 } /* Name.Variable.Instance */
-  .il { color: #009999 } /* Literal.Number.Integer.Long */
+  .c { color: #999988; font-style: italic } // Comment
+  .err { color: #a61717; background-color: #e3d2d2 } // Error
+  .k { color: #000000; font-weight: bold } // Keyword
+  .o { color: #000000; font-weight: bold } // Operator
+  .cm { color: #999988; font-style: italic } // Comment.Multiline
+  .cp { color: #999999; font-weight: bold } // Comment.Preproc
+  .c1 { color: #999988; font-style: italic } // Comment.Single
+  .cs { color: #999999; font-weight: bold; font-style: italic } // Comment.Special
+  .gd { color: #000000; background-color: #ffdddd } // Generic.Deleted
+  .gd .x { color: #000000; background-color: #ffaaaa } // Generic.Deleted.Specific
+  .ge { color: #000000; font-style: italic } // Generic.Emph
+  .gr { color: #aa0000 } // Generic.Error
+  .gh { color: #999999 } // Generic.Heading
+  .gi { color: #000000; background-color: #ddffdd } // Generic.Inserted
+  .gi .x { color: #000000; background-color: #aaffaa } // Generic.Inserted.Specific
+  .go { color: #888888 } // Generic.Output
+  .gp { color: #555555 } // Generic.Prompt
+  .gs { font-weight: bold } // Generic.Strong
+  .gu { color: #aaaaaa } // Generic.Subheading
+  .gt { color: #aa0000 } // Generic.Traceback
+  .kc { color: #000000; font-weight: bold } // Keyword.Constant
+  .kd { color: #000000; font-weight: bold } // Keyword.Declaration
+  .kp { color: #000000; font-weight: bold } // Keyword.Pseudo
+  .kr { color: #000000; font-weight: bold } // Keyword.Reserved
+  .kt { color: #445588; } // Keyword.Type
+  .m { color: #009999 } // Literal.Number
+  .s { color: #d14 } // Literal.String
+  .na { color: #008080 } // Name.Attribute
+  .nb { color: #0086B3 } // Name.Builtin
+  .nc { color: #445588; font-weight: bold } // Name.Class
+  .no { color: #008080 } // Name.Constant
+  .ni { color: #800080 } // Name.Entity
+  .ne { color: #990000; font-weight: bold } // Name.Exception
+  .nf { color: #990000; } // Name.Function
+  .nn { color: #555555 } // Name.Namespace
+  .nt { color: #000080 } // Name.Tag
+  .nv { color: #008080 } // Name.Variable
+  .ow { color: #000000; font-weight: bold } // Operator.Word
+  .w { color: #bbbbbb } // Text.Whitespace
+  .mf { color: #009999 } // Literal.Number.Float
+  .mh { color: #009999 } // Literal.Number.Hex
+  .mi { color: #009999 } // Literal.Number.Integer
+  .mo { color: #009999 } // Literal.Number.Oct
+  .sb { color: #d14 } // Literal.String.Backtick
+  .sc { color: #d14 } // Literal.String.Char
+  .sd { color: #d14 } // Literal.String.Doc
+  .s2 { color: #d14 } // Literal.String.Double
+  .se { color: #d14 } // Literal.String.Escape
+  .sh { color: #d14 } // Literal.String.Heredoc
+  .si { color: #d14 } // Literal.String.Interpol
+  .sx { color: #d14 } // Literal.String.Other
+  .sr { color: #009926 } // Literal.String.Regex
+  .s1 { color: #d14 } // Literal.String.Single
+  .ss { color: #990073 } // Literal.String.Symbol
+  .bp { color: #999999 } // Name.Builtin.Pseudo
+  .vc { color: #008080 } // Name.Variable.Class
+  .vg { color: #008080 } // Name.Variable.Global
+  .vi { color: #008080 } // Name.Variable.Instance
+  .il { color: #009999 } // Literal.Number.Integer.Long
 }

data/lib/jazzy/themes/apple/assets/css/jazzy.css.scss

@@ -1,3 +1,7 @@
+/*! Jazzy - https://github.com/realm/jazzy
+ *  Copyright Realm Inc.
+ *  SPDX-License-Identifier: MIT
+ */
 ////////////////////////////////
 // Constants
 ////////////////////////////////
@@ -23,7 +27,8 @@ $breadcrumb_padding_top: 17px;
 
 $code_font: 0.95em Menlo, monospace;
 
-$gray_border: 1px solid #e2e2e2;
+$gray_border_color: #e2e2e2;
+$gray_border: 1px solid $gray_border_color;
 $declaration_language_border: 5px solid #cde9f4;
 
 $aside_color: #aaa;
@@ -141,6 +146,25 @@ blockquote {
   border-left: 4px solid #ccc;
 }
 
+// HRs
+
+hr {
+  height: 1px;
+  border: none;
+  background-color: $gray_border_color;
+}
+
+// Footnotes
+
+.footnote-ref {
+  display: inline-block;
+  scroll-margin-top: $content-top-offset;
+}
+
+.footnote-def {
+  scroll-margin-top: $content-top-offset;
+}
+
 // General Content Wrapper
 
 .content-wrapper {
@@ -161,7 +185,7 @@ header {
   z-index: 3;
   img {
     padding-right: 6px;
-    vertical-align: -4px;
+    vertical-align: -3px;
     height: 16px;
   }
   a {

data/lib/jazzy/themes/apple/assets/js/jazzy.js

@@ -1,3 +1,7 @@
+// Jazzy - https://github.com/realm/jazzy
+// Copyright Realm Inc.
+// SPDX-License-Identifier: MIT
+
 window.jazzy = {'docset': false}
 if (typeof window.dash != 'undefined') {
   document.documentElement.className += ' dash'

data/lib/jazzy/themes/apple/assets/js/jazzy.search.js

@@ -1,3 +1,7 @@
+// Jazzy - https://github.com/realm/jazzy
+// Copyright Realm Inc.
+// SPDX-License-Identifier: MIT
+
 $(function(){
   var $typeahead = $('[data-typeahead]');
   var $form = $typeahead.parents('form');