jazzy 0.14.4 → 0.15.0

data/lib/jazzy/symbol_graph/ext_key.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Jazzy
+  module SymbolGraph
+    # An ExtKey identifies an extension of a type, made up of the USR of
+    # the type and the constraints of the extension.  With Swift 5.9 extension
+    # symbols, the USR is the 'fake' USR invented by symbolgraph to solve the
+    # same problem as this type, which means less merging takes place.
+    class ExtKey
+      attr_accessor :usr
+      attr_accessor :constraints_text
+
+      def initialize(usr, constraints)
+        self.usr = usr
+        self.constraints_text = constraints.map(&:to_swift).join
+      end
+
+      def hash_key
+        usr + constraints_text
+      end
+
+      def eql?(other)
+        hash_key == other.hash_key
+      end
+
+      def hash
+        hash_key.hash
+      end
+    end
+
+    class ExtSymNode
+      def ext_key
+        ExtKey.new(usr, all_constraints.ext)
+      end
+    end
+  end
+end

data/lib/jazzy/symbol_graph/ext_node.rb

@@ -23,6 +23,7 @@ module Jazzy
     # an extension that we fabricate to resolve certain relationships.
     class ExtNode < BaseNode
       attr_accessor :usr
+      attr_accessor :real_usr
       attr_accessor :name
       attr_accessor :all_constraints # ExtConstraints
       attr_accessor :conformances # array, can be empty
@@ -75,15 +76,15 @@ module Jazzy
         decl + all_constraints.ext.to_where_clause
       end
 
-      def to_sourcekit(module_name)
+      def to_sourcekit(module_name, ext_module_name)
         declaration = full_declaration
         xml_declaration = "<swift>#{CGI.escapeHTML(declaration)}</swift>"
 
         hash = {
           'key.kind' => 'source.lang.swift.decl.extension',
-          'key.usr' => usr,
+          'key.usr' => real_usr || usr,
           'key.name' => name,
-          'key.modulename' => module_name,
+          'key.modulename' => ext_module_name,
           'key.parsed_declaration' => declaration,
           'key.annotated_decl' => xml_declaration,
         }
@@ -94,9 +95,7 @@ module Jazzy
           end
         end
 
-        unless children.empty?
-          hash['key.substructure'] = children_to_sourcekit
-        end
+        add_children_to_sourcekit(hash, module_name)
 
         hash
       end
@@ -112,5 +111,23 @@ module Jazzy
         sort_key <=> other.sort_key
       end
     end
+
+    # An ExtSymNode is an extension generated from a Swift 5.9 extension
+    # symbol, for extensions of types from other modules only.
+    class ExtSymNode < ExtNode
+      attr_accessor :symbol
+
+      def initialize(symbol)
+        self.symbol = symbol
+        super(symbol.usr, symbol.full_name,
+              # sadly can't tell what constraints are inherited vs added
+              ExtConstraints.new([], symbol.constraints))
+      end
+
+      def to_sourcekit(module_name, ext_module_name)
+        hash = super
+        symbol.add_to_sourcekit(hash)
+      end
+    end
   end
 end

data/lib/jazzy/symbol_graph/graph.rb

@@ -7,37 +7,40 @@ module Jazzy
     # 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 :module_name # Our module
+      attr_accessor :ext_module_name # Module being extended
       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)
+      def initialize(json, module_name, ext_module_name)
         self.module_name = module_name
+        self.ext_module_name = ext_module_name
         graph = JSON.parse(json, symbolize_names: true)
 
         self.symbol_nodes = {}
+        self.ext_nodes = {}
+
         graph[:symbols].each do |hash|
           symbol = Symbol.new(hash)
-          symbol_nodes[symbol.usr] = SymNode.new(symbol)
+          if symbol.extension?
+            node = ExtSymNode.new(symbol)
+            ext_nodes[node.ext_key] = node
+          else
+            symbol_nodes[symbol.usr] = SymNode.new(symbol)
+          end
         end
 
         self.relationships =
           graph[:relationships].map { |hash| Relationship.new(hash) }
-
-        self.ext_nodes = {}
       end
 
-      # ExtNode index.  (type USR, extension constraints) -> ExtNode.
+      # ExtNode index.  ExtKey (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)
+        key = ExtKey.new(type_usr, constraints.ext)
         if ext_node = ext_nodes[key]
           ext_node.add_child(member_node)
         else
@@ -50,7 +53,7 @@ module Jazzy
                               type_name,
                               protocol,
                               constraints)
-        key = ext_key(type_usr, constraints.ext)
+        key = ExtKey.new(type_usr, constraints.ext)
         if ext_node = ext_nodes[key]
           ext_node.add_conformance(protocol)
         else
@@ -149,6 +152,15 @@ module Jazzy
         end
       end
 
+      # "References to fake_usr should be real_usr"
+      def unalias_extensions(fake_usr, real_usr)
+        ext_nodes.each_pair do |key, ext|
+          if key.usr == fake_usr
+            ext.real_usr = real_usr
+          end
+        end
+      end
+
       # Process a structural relationship to link nodes
       def rebuild_rel(rel)
         source = symbol_nodes[rel.source_usr]
@@ -166,29 +178,29 @@ module Jazzy
 
         when :inheritsFrom
           rebuild_inherits(rel, source, target)
+
+        when :extensionTo
+          unalias_extensions(rel.source_usr, rel.target_usr)
         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) }
+        relationships.sort.each { |r| rebuild_rel(r) }
 
         root_symbol_nodes =
           symbol_nodes.values
             .select(&:top_level_decl?)
             .sort
-            .map(&:to_sourcekit)
+            .map { |n| n.to_sourcekit(module_name) }
 
         root_ext_nodes =
           ext_nodes.values
             .sort
-            .map { |n| n.to_sourcekit(module_name) }
+            .map { |n| n.to_sourcekit(module_name, ext_module_name) }
         {
           'key.diagnostic_stage' => 'parse',
           'key.substructure' => root_symbol_nodes + root_ext_nodes,

data/lib/jazzy/symbol_graph/relationship.rb

@@ -10,9 +10,14 @@ module Jazzy
       attr_accessor :target_fallback # can be nil
       attr_accessor :constraints # array, can be empty
 
-      KINDS = %w[memberOf conformsTo defaultImplementationOf
-                 overrides inheritsFrom requirementOf
-                 optionalRequirementOf].freeze
+      # Order matters: defaultImplementationOf after the protocols
+      # have been defined; extensionTo after all the extensions have
+      # been discovered.
+      KINDS = %w[memberOf conformsTo overrides inheritsFrom
+                 requirementOf optionalRequirementOf
+                 defaultImplementationOf extensionTo].freeze
+
+      KINDS_INDEX = KINDS.to_h { |i| [i.to_sym, KINDS.index(i)] }.freeze
 
       def protocol_requirement?
         %i[requirementOf optionalRequirementOf].include? kind
@@ -22,6 +27,10 @@ module Jazzy
         kind == :defaultImplementationOf
       end
 
+      def extension_to?
+        kind == :extensionTo
+      end
+
       # Protocol conformances added by compiler to actor decls that
       # users aren't interested in.
       def actor_protocol?
@@ -43,6 +52,15 @@ module Jazzy
         end
         self.constraints = Constraint.new_list(hash[:swiftConstraints] || [])
       end
+
+      # Sort order
+      include Comparable
+
+      def <=>(other)
+        return 0 if kind == other.kind
+
+        KINDS_INDEX[kind] <=> KINDS_INDEX[other.kind]
+      end
     end
   end
 end

data/lib/jazzy/symbol_graph/sym_node.rb

@@ -18,14 +18,16 @@ module Jazzy
         children.append(child)
       end
 
-      def children_to_sourcekit
-        children.sort.map(&:to_sourcekit)
+      def add_children_to_sourcekit(hash, module_name)
+        unless children.empty?
+          hash['key.substructure'] =
+            children.sort.map { |c| c.to_sourcekit(module_name) }
+        end
       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
@@ -128,8 +130,7 @@ module Jazzy
           .join("\n")
       end
 
-      # rubocop:disable Metrics/MethodLength
-      def to_sourcekit
+      def to_sourcekit(module_name)
         declaration = full_declaration
         xml_declaration = "<swift>#{CGI.escapeHTML(declaration)}</swift>"
 
@@ -137,32 +138,20 @@ module Jazzy
           'key.kind' => symbol.kind,
           'key.usr' => symbol.usr,
           'key.name' => symbol.name,
-          'key.accessibility' => symbol.acl,
-          'key.parsed_decl' => declaration,
+          'key.modulename' => module_name,
+          'key.parsed_declaration' => 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
+        add_children_to_sourcekit(hash, module_name)
+        symbol.add_to_sourcekit(hash)
       end
-      # rubocop:enable Metrics/MethodLength
 
       # Sort order - by symbol
       include Comparable
@@ -171,6 +160,5 @@ module Jazzy
         symbol <=> other.symbol
       end
     end
-    # rubocop:enable Metrics/ClassLength
   end
 end

data/lib/jazzy/symbol_graph/symbol.rb

@@ -22,6 +22,10 @@ module Jazzy
         path_components[-1] || '??'
       end
 
+      def full_name
+        path_components.join('.')
+      end
+
       def initialize(hash)
         self.usr = hash[:identifier][:precise]
         self.path_components = hash[:pathComponents]
@@ -101,6 +105,7 @@ module Jazzy
         'associatedtype' => 'associatedtype',
         'actor' => 'actor',
         'macro' => 'macro',
+        'extension' => 'extension',
       }.freeze
 
       # We treat 'static var' differently to 'class var'
@@ -122,6 +127,10 @@ module Jazzy
         self.kind = "source.lang.swift.decl.#{sourcekit_kind}"
       end
 
+      def extension?
+        kind.end_with?('extension')
+      end
+
       # Mapping SymbolGraph's ACL to SourceKit
 
       def init_acl(acl)
@@ -217,6 +226,25 @@ module Jazzy
           availability_attributes(avail_hash_list) + spi_attributes
       end
 
+      # SourceKit common fields, shared by extension and regular symbols.
+      # Things we do not know for fabricated extensions.
+      def add_to_sourcekit(hash)
+        unless doc_comments.nil?
+          hash['key.doc.comment'] = doc_comments
+          hash['key.doc.full_as_xml'] = ''
+        end
+
+        hash['key.accessibility'] = acl
+
+        unless location.nil?
+          hash['key.filepath'] = location[:filename]
+          hash['key.doc.line'] = location[:line] + 1
+          hash['key.doc.column'] = location[:character] + 1
+        end
+
+        hash
+      end
+
       # Sort order
       include Comparable
 

data/lib/jazzy/symbol_graph.rb

@@ -7,6 +7,7 @@ require 'jazzy/symbol_graph/symbol'
 require 'jazzy/symbol_graph/relationship'
 require 'jazzy/symbol_graph/sym_node'
 require 'jazzy/symbol_graph/ext_node'
+require 'jazzy/symbol_graph/ext_key'
 
 # This is the top-level symbolgraph driver that deals with
 # figuring out arguments, running the tool, and loading the
@@ -19,10 +20,10 @@ module Jazzy
     # with configured args.
     # Then parse the results, and return as JSON in SourceKit[ten]
     # format.
-    def self.build(config)
-      if config.symbolgraph_directory.nil?
+    def self.build(module_config)
+      if module_config.symbolgraph_directory.nil?
         Dir.mktmpdir do |tmp_dir|
-          args = arguments(config, tmp_dir)
+          args = arguments(module_config, tmp_dir)
 
           Executable.execute_command('swift',
                                      args.unshift('symbolgraph-extract'),
@@ -31,17 +32,17 @@ module Jazzy
           parse_symbols(tmp_dir)
         end
       else
-        parse_symbols(config.symbolgraph_directory.to_s)
+        parse_symbols(module_config.symbolgraph_directory.to_s)
       end
     end
 
     # Figure out the args to pass to symbolgraph-extract
-    def self.arguments(config, output_path)
-      if config.module_name.empty?
+    def self.arguments(module_config, output_path)
+      if module_config.module_name.empty?
         raise 'error: `--swift-build-tool symbolgraph` requires `--module`.'
       end
 
-      user_args = config.build_tool_arguments.join
+      user_args = module_config.build_tool_arguments.join
 
       if user_args =~ /-(?:module-name|minimum-access-level|output-dir)/
         raise 'error: `--build-tool-arguments` for ' \
@@ -51,19 +52,19 @@ module Jazzy
 
       # Default set
       args = [
-        '-module-name', config.module_name,
+        '-module-name', module_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 += ['-sdk', sdk(module_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 += ['-F', module_config.source_directory.to_s] unless user_args =~ /-F(?!s)/
+      args += ['-I', module_config.source_directory.to_s] unless user_args =~ /-I/
 
-      args + config.build_tool_arguments
+      args + module_config.build_tool_arguments
     end
 
     # Parse the symbol files in the given directory
@@ -72,17 +73,19 @@ module Jazzy
         # The @ part is for extensions in our module (before the @)
         # of types in another module (after the @).
         File.basename(filename) =~ /(.*?)(@(.*?))?\.symbols/
-        module_name = Regexp.last_match[3] || Regexp.last_match[1]
+        module_name = Regexp.last_match[1]
+        ext_module_name = Regexp.last_match[3] || module_name
+        json = File.read(filename)
         {
           filename =>
-            Graph.new(File.read(filename), module_name).to_sourcekit,
+            Graph.new(json, module_name, ext_module_name).to_sourcekit,
         }
       end.to_json
     end
 
     # Get the SDK path.  On !darwin this just isn't needed.
-    def self.sdk(config)
-      `xcrun --show-sdk-path --sdk #{config.sdk}`.chomp
+    def self.sdk(module_config)
+      `xcrun --show-sdk-path --sdk #{module_config.sdk}`.chomp
     end
 
     # Guess a default LLVM target.  Feels like the tool should figure this

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

@@ -23,7 +23,7 @@ $content_top_offset: 70px;
 $content_body_margin: 16px;
 $content_body_left_offset: $sidebar_width + $content_body_margin;
 $header_height: 32px;
-$breadcrumb_padding_top: 17px;
+$breadcrumb_padding_top: 12px;
 
 $code_font: 0.95em Menlo, monospace;
 
@@ -206,9 +206,11 @@ header {
   height: $content_top_offset - $header_height - $breadcrumb_padding_top;
   padding-top: $breadcrumb_padding_top;
   position: fixed;
-  width: 100%;
+  width: inherit;
   z-index: 2;
   margin-top: $header_height;
+  white-space: nowrap;
+  overflow-x: scroll;
   #carat {
     height: 10px;
     margin: 0 5px;
@@ -412,11 +414,12 @@ header {
   .discouraged {
     text-decoration: line-through;
   }
-  .declaration-note {
-    font-size: .85em;
-    color: rgba(128,128,128,1);
-    font-style: italic;
-  }
+}
+
+.declaration-note {
+  font-size: .85em;
+  color: rgba(128,128,128,1);
+  font-style: italic;
 }
 
 .pointer-container {

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

@@ -1,7 +1,7 @@
 /*!
- * typeahead.js 1.3.1
+ * typeahead.js 1.3.3
  * https://github.com/corejavascript/typeahead.js
- * Copyright 2013-2020 Twitter, Inc. and other contributors; Licensed MIT
+ * Copyright 2013-2024 Twitter, Inc. and other contributors; Licensed MIT
  */
 
 
@@ -499,6 +499,7 @@
             });
             this.$input.attr({
                 "aria-owns": id + "_listbox",
+                "aria-controls": id + "_listbox",
                 role: "combobox",
                 "aria-autocomplete": "list",
                 "aria-expanded": false

data/lib/jazzy/themes/apple/templates/doc.mustache

@@ -28,9 +28,16 @@
     {{> header}}
     <div class="content-wrapper">
       <p id="breadcrumbs">
-        <a href="{{path_to_root}}index.html">{{module_name}} Reference</a>
+        <a href="{{path_to_root}}index.html">{{readme_title}}</a>
+        {{#breadcrumbs}}
         <img id="carat" src="{{path_to_root}}img/carat.png" alt=""/>
+        {{#last}}
         {{name}} {{kind}} Reference
+        {{/last}}
+        {{^last}}
+        <a href="{{path_to_root}}{{url}}">{{name}}</a>
+        {{/last}}
+        {{/breadcrumbs}}
       </p>
     </div>
     <div class="content-wrapper">

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

@@ -454,12 +454,12 @@ pre code {
     margin-left: 20px;
     font-size: 1rem;
   }
+}
 
-  .declaration-note {
-    font-size: .85em;
-    color: #808080;
-    font-style: italic;
-  }
+.declaration-note {
+  font-size: .85em;
+  color: #808080;
+  font-style: italic;
 }
 
 .pointer-container {

data/lib/jazzy/themes/fullwidth/assets/js/typeahead.jquery.js

@@ -1,7 +1,7 @@
 /*!
- * typeahead.js 1.3.1
+ * typeahead.js 1.3.3
  * https://github.com/corejavascript/typeahead.js
- * Copyright 2013-2020 Twitter, Inc. and other contributors; Licensed MIT
+ * Copyright 2013-2024 Twitter, Inc. and other contributors; Licensed MIT
  */
 
 
@@ -499,6 +499,7 @@
             });
             this.$input.attr({
                 "aria-owns": id + "_listbox",
+                "aria-controls": id + "_listbox",
                 role: "combobox",
                 "aria-autocomplete": "list",
                 "aria-expanded": false

data/lib/jazzy/themes/fullwidth/templates/doc.mustache

@@ -31,9 +31,16 @@
     {{> header}}
 
     <p class="breadcrumbs">
-      <a class="breadcrumb" href="{{path_to_root}}index.html">{{module_name}} Reference</a>
+      <a class="breadcrumb" href="{{path_to_root}}index.html">{{readme_title}}</a>
+      {{#breadcrumbs}}
       <img class="carat" src="{{path_to_root}}img/carat.png" alt=""/>
+      {{#last}}
       {{name}} {{kind}} Reference
+      {{/last}}
+      {{^last}}
+      <a class="breadcrumb" href="{{path_to_root}}{{url}}">{{name}}</a>
+      {{/last}}
+      {{/breadcrumbs}}
     </p>
 
     <div class="content-wrapper">

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

@@ -450,11 +450,12 @@ header {
   .token-open {
     margin-left: 45px;
   }
-  .declaration-note {
-    font-size: .85em;
-    color: rgba(128,128,128,1);
-    font-style: italic;
-  }
+}
+
+.declaration-note {
+  font-size: .85em;
+  color: rgba(128,128,128,1);
+  font-style: italic;
 }
 
 .pointer-container {

data/lib/jazzy/themes/jony/templates/doc.mustache

@@ -26,10 +26,17 @@
       <div class="content-wrapper">
         <p id="breadcrumbs">
           <span class="no-mobile">
-            <a href="{{path_to_root}}index.html">{{module_name}} Reference</a>
+            <a href="{{path_to_root}}index.html">{{readme_title}}</a>
+            {{#breadcrumbs}}
             <img id="carat" src="{{path_to_root}}img/carat.png" alt=""/>
+            {{#last}}
+            {{name}} {{kind}} Reference
+            {{/last}}
+            {{^last}}
+            <a href="{{path_to_root}}{{url}}">{{name}}</a>
+            {{/last}}
+            {{/breadcrumbs}}
           </span>
-          {{name}} {{kind}} Reference
         </p>
       </div>
     </div>

data/spec/integration_spec.rb

@@ -121,6 +121,8 @@ describe_cli 'jazzy' do
     s.replace_pattern(%r{/transformed/}, '/')
     # Xcode 15 workaround
     s.replace_pattern(/objc\[.....\]: Class _?DTX\w+ is implemented in both.*?\n/, '')
+    # arm vs. intel workaround
+    s.replace_pattern(%r{(?<=build/)(arm64|x86_64)(?=-apple)}, '')
   end
 
   require 'shellwords'
@@ -246,7 +248,12 @@ describe_cli 'jazzy' do
       module_path = `swift build --scratch-path #{build_path} --show-bin-path`
       behaves_like cli_spec 'misc_jazzy_symgraph_features',
                             '--swift-build-tool symbolgraph ' \
-                              "--build-tool-arguments -I,#{module_path} "
+                              '--build-tool-arguments ' \
+                              "-emit-extension-block-symbols,-I,#{module_path}"
+    end
+
+    describe 'Creates docs for a multiple-module project' do
+      behaves_like cli_spec 'jazzy_multi_modules'
     end
   end if !spec_subset || spec_subset == 'swift'