yard 0.9.43 → 0.9.44

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 92d411c4d39cc74df916cbac8719ebd7ac6ed1fb17b37022148f584440bda554
-  data.tar.gz: 9582c48d6c1949c055e22035f325abc957ec31900613f5b04307f7f27fc011a4
+  metadata.gz: 87aef8f8a0b6c25d1a2c05214992313aa6278659214af6650d07876346b771ec
+  data.tar.gz: 149cee78996a555a97d7223252df845be60ecaf9bf92d7c9bedeeb8fe14952bf
 SHA512:
-  metadata.gz: d566d6989e868b3bc4959037309c9c07a89608f07a39ad2719ead8765fca6ab3ae6240bfe7d56394ad47c8d75c5999d02313f6f7eaedb056a2ea584750d15cc1
-  data.tar.gz: 641e462842732b47a67ff95eda6cfdb0373de7b2f487ceb7aa827815c0f8201fa55639979f7df17ec4d12864de60c4cc631fc7921cc787b20a04f5493cd86033
+  metadata.gz: e7bd349e0d31fb2b79dd0c18a057ff9323206c4d6be3535f902f9fa45ee30a8649bd3036861fdf2ab90e017bfaf7622eb744461a2728a88b68792bc8acbd3fa9
+  data.tar.gz: 2f4e486d27daf722a02c2efc2e7af568c12a76ebd30b23871a46c25c54e03f9e6f51397953dac330dba6b0581b7088882e581b04f43fe9ef64e3a0a93862df15

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # main
 
+# [0.9.44] - May 25th, 2026
+
+[0.9.44]: https://github.com/lsegal/yard/compare/v0.9.43...v0.9.44
+
+- Fix possible path traversal with document_root (`--docroot`) and disk caching (`--cache`) set in `yard server` ([GHSA-pxcc-8665-phx8](https://github.com/lsegal/yard/security/advisories/GHSA-pxcc-8665-phx8))
+- Fix support for HTML entities in HybridMarkup (#1680, #1681)
+- Add support for string literals in TypesExplainer (#1628)
+- Add support for multiple & nested Hash keys definition (#1630)
+
 # [0.9.43] - April 17th, 2026
 
 [0.9.43]: https://github.com/lsegal/yard/compare/v0.9.42...v0.9.43

data/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2007-2022 Loren Segal
+Copyright (c) 2007-2026 Loren Segal
 
 Permission is hereby granted, free of charge, to any person
 obtaining a copy of this software and associated documentation

data/README.md

@@ -323,7 +323,7 @@ See {file:CHANGELOG.md} for a list of changes.
 
 ## License
 
-YARD © 2007-2020 by [Loren Segal](mailto:lsegal@soen.ca). YARD is licensed
+YARD © by [Loren Segal](mailto:lsegal@soen.ca). YARD is licensed
 under the MIT license except for some files which come from the RDoc/Ruby
 distributions. Please see the {file:LICENSE} and {file:LEGAL} documents for more
 information.

data/docs/Tags.md

@@ -201,6 +201,27 @@ in the form `Hash<KeyType, ValueType>`, or using the hash specific syntax:
 `Hash{KeyTypes=>ValueTypes}`. In the latter case, KeyTypes or ValueTypes can
 also be a list of types separated by commas.
 
+For more precise type signatures, the hash-specific syntax also supports
+multiple keys mapping to the same value type(s), multiple key/value groups,
+and nested hashes:
+
+* **Multiple keys for the same value type(s)** &mdash; A comma-separated list of
+  keys on the left of `=>` all share the value types on the right. For example,
+  `Hash{:name, :title => String}` describes a Hash where both `:name` and
+  `:title` keys map to String values.
+* **Multiple key/value groups** &mdash; Separate distinct key/value groups with
+  a semicolon (`;`). For example,
+  `Hash{:name => String; :age => Integer}` describes a Hash with a `:name` key
+  that maps to a String and an `:age` key that maps to an Integer.
+* **Nested hashes** &mdash; A value type can itself be a hash, allowing nested
+  structures. For example,
+  `Hash{:user => Hash{:name => String, :age => Integer}}` describes a Hash with
+  a `:user` key whose value is another Hash with `:name` and `:age` keys.
+
+Keys in the hash-specific syntax are commonly [literal values](#Literals) such
+as symbols (`:key`) or strings (`'key'`, `"key"`), but any type listed in the
+[type conventions](#Type_List_Conventions) is allowed.
+
 #### Order-Dependent Lists
 
 An order dependent list is a set of types surrounded by "()" and separated by
@@ -213,7 +234,7 @@ having exactly those 3 elements) would be listed as: `Array(String, Fixnum, Hash
 Some literals are accepted by virtue of being Ruby literals, but also by YARD
 conventions. Here is a non-exhaustive list of certain accepted literal values:
 
-* `true`, `false`, `nil`, `:foo` &mdash; used when a method returns
+* `true`, `false`, `nil`, `:foo`, `"bar"` &mdash; used when a method returns
   these explicit literal values. Note that if your method returns both
   `true` or `false`, you should use the `Boolean` conventional type
   instead.

data/lib/yard/autoload.rb

@@ -287,6 +287,7 @@ module YARD
   module Templates
     module Helpers # Namespace for template helpers
       module Markup # Namespace for markup providers
+        autoload :HtmlEntities,              __p('templates/helpers/markup/html_entities')
         autoload :HybridMarkdown,           __p('templates/helpers/markup/hybrid_markdown')
         autoload :RDocMarkup,               __p('templates/helpers/markup/rdoc_markup')
         autoload :RDocMarkdown,             __p('templates/helpers/markup/rdoc_markdown')

data/lib/yard/server/commands/base.rb

@@ -1,6 +1,4 @@
 # frozen_string_literal: true
-require 'fileutils'
-
 module YARD
   module Server
     module Commands
@@ -32,6 +30,8 @@ module YARD
       # @abstract
       # @see #run
       class Base
+        include StaticCaching
+
         # @group Basic Command and Adapter Options
 
         # @return [Hash] the options passed to the command's constructor
@@ -163,13 +163,7 @@ module YARD
         # @return [String] the same cached data (for chaining)
         # @see StaticCaching
         def cache(data)
-          if caching && adapter.document_root
-            path = File.join(adapter.document_root, request.path_info.sub(/\.html$/, '') + '.html')
-            path = path.sub(%r{/\.html$}, '.html')
-            FileUtils.mkdir_p(File.dirname(path))
-            log.debug "Caching data to #{path}"
-            File.open(path, 'wb') {|f| f.write(data) }
-          end
+          super if caching
           self.body = data
         end
 

data/lib/yard/server/static_caching.rb

@@ -1,4 +1,6 @@
 # frozen_string_literal: true
+require 'fileutils'
+
 module YARD
   module Server
     # Implements static caching for requests.
@@ -10,9 +12,8 @@ module YARD
       # implement your own +#check_static_cache+ method and mix the module into
       # the Router class.
       #
-      # Note that caching does not occur here. This method simply checks for
-      # the existence of cached data. To actually cache a response, see
-      # {Commands::Base#cache}.
+      # This method checks for the existence of cached data. To actually cache
+      # a response, see {#cache}.
       #
       # @example Implementing In-Memory Cache Checking
       #   module MemoryCaching
@@ -33,14 +34,44 @@ module YARD
       # @see Commands::Base#cache
       def check_static_cache
         return nil unless adapter.document_root
-        cache_path = File.join(adapter.document_root, request.path.sub(/\.html$/, '') + '.html')
-        cache_path = cache_path.sub(%r{/\.html$}, '.html')
+        cache_path = cache_path(request.path)
+        return nil unless cache_path
+
         if File.file?(cache_path)
           log.debug "Loading cache from disk: #{cache_path}"
           return [200, {'Content-Type' => 'text/html'}, [File.read_binary(cache_path)]]
         end
         nil
       end
+
+      # Caches rendered HTML response data to disk.
+      #
+      # @param [String] data the data to cache
+      # @return [void]
+      # @since 0.9.44
+      def cache(data)
+        return unless adapter.document_root
+
+        path = cache_path(request.path_info)
+        return unless path
+
+        FileUtils.mkdir_p(File.dirname(path))
+        log.debug "Caching data to #{path}"
+        File.open(path, 'wb') {|f| f.write(data) }
+      end
+
+      private
+
+      def cache_path(request_path)
+        return nil if request_path.split(/[\/\\]/).include?('..')
+
+        path = request_path.sub(/\.html$/, '') + '.html'
+        path = path.sub(%r{\A/+}, '')
+        return nil if path =~ /\A[A-Za-z]:/
+
+        path = File.cleanpath(path)
+        File.join(adapter.document_root, path)
+      end
     end
   end
 end

data/lib/yard/tags/types_explainer.rb

@@ -4,6 +4,9 @@ require 'strscan'
 module YARD
   module Tags
     class TypesExplainer
+      # Regular expression to match symbol and string literals
+      LITERALMATCH = /:\w+|'[^']*'|"[^"]*"/
+
       # (see Tag#explain_types)
       # @param types [Array<String>] a list of types to parse and summarize
       def self.explain(*types)
@@ -31,16 +34,14 @@ module YARD
         end
 
         def to_s(singular = true)
-          if name[0, 1] == "#"
-            (singular ? "an object that responds to " : "objects that respond to ") + list_join(name.split(/ *& */), with: "and")
-          elsif name[0, 1] =~ /[A-Z]/
+          if name[0, 1] =~ /[A-Z]/
             singular ? "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} " + name : "#{name}#{name[-1, 1] =~ /[A-Z]/ ? "'" : ''}s"
           else
             name
           end
         end
 
-        private
+        protected
 
         def list_join(list, with: "or")
           index = 0
@@ -54,6 +55,20 @@ module YARD
         end
       end
 
+      # @private
+      class LiteralType < Type
+        def to_s(_singular = true)
+          "a literal value #{name}"
+        end
+      end
+
+      # @private
+      class DuckType < Type
+        def to_s(singular = true)
+          (singular ? "an object that responds to " : "objects that respond to ") + list_join(name.split(/ *& */), with: "and")
+        end
+      end
+
       # @private
       class CollectionType < Type
         attr_accessor :types
@@ -77,18 +92,56 @@ module YARD
 
       # @private
       class HashCollectionType < Type
-        attr_accessor :key_types, :value_types
+        attr_accessor :key_value_pairs
 
-        def initialize(name, key_types, value_types)
+        def initialize(name, key_types_or_pairs, value_types = nil)
           @name = name
-          @key_types = key_types
-          @value_types = value_types
+
+          if value_types.nil?
+            # New signature: (name, key_value_pairs)
+            @key_value_pairs = key_types_or_pairs || []
+          else
+            # Old signature: (name, key_types, value_types)
+            @key_value_pairs = [[key_types_or_pairs, value_types]]
+          end
+        end
+
+        # Backward compatibility accessors
+        def key_types
+          return [] if @key_value_pairs.empty?
+          @key_value_pairs.first[0] || []
+        end
+
+        def key_types=(types)
+          if @key_value_pairs.empty?
+            @key_value_pairs = [[types, []]]
+          else
+            @key_value_pairs[0][0] = types
+          end
+        end
+
+        def value_types
+          return [] if @key_value_pairs.empty?
+          @key_value_pairs.first[1] || []
+        end
+
+        def value_types=(types)
+          if @key_value_pairs.empty?
+            @key_value_pairs = [[[], types]]
+          else
+            @key_value_pairs[0][1] = types
+          end
         end
 
         def to_s(_singular = true)
-          "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} with keys made of (" +
-            list_join(key_types.map {|t| t.to_s(false) }) +
-            ") and values of (" + list_join(value_types.map {|t| t.to_s(false) }) + ")"
+          return "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name}" if @key_value_pairs.empty?
+
+          result = "a#{name[0, 1] =~ /[aeiou]/i ? 'n' : ''} #{name} with "
+          parts = @key_value_pairs.map do |keys, values|
+            "keys made of (" + list_join(keys.map {|t| t.to_s(false) }) +
+            ") and values of (" + list_join(values.map {|t| t.to_s(false) }) + ")"
+          end
+          result + parts.join(" and ")
         end
       end
 
@@ -101,13 +154,15 @@ module YARD
           :collection_end => />/,
           :fixed_collection_start => /\(/,
           :fixed_collection_end => /\)/,
-          :type_name => /#{ISEP}#{METHODNAMEMATCH}|#{NAMESPACEMATCH}|\w+/,
+          :type_name => /#{ISEP}#{METHODNAMEMATCH}|#{NAMESPACEMATCH}|#{LITERALMATCH}|\w+/,
           :symbol => /:#{METHODNAMEMATCH}/,
-          :type_next => /[,;]/,
+          :type_next => /[,]/,
           :whitespace => /\s+/,
           :hash_collection_start => /\{/,
-          :hash_collection_next => /=>/,
+          :hash_collection_value => /=>/,
+          :hash_collection_value_end => /;/,
           :hash_collection_end => /\}/,
+          # :symbol_start => /:/,
           :parse_end => nil
         }
 
@@ -119,10 +174,45 @@ module YARD
           @scanner = StringScanner.new(string)
         end
 
-        def parse
-          types = []
+        # @return [Array(Boolean, Array<Type>)] - finished, types
+        def parse(until_tokens: [:parse_end])
+          current_parsed_types = []
           type = nil
           name = nil
+          finished = false
+          parse_with_handlers do |token_type, token|
+            case token_type
+            when *until_tokens
+              raise SyntaxError, "expecting name, got '#{token}'" if name.nil?
+              type = create_type(name) unless type
+              current_parsed_types << type
+              finished = true
+            when :type_name
+              raise SyntaxError, "expecting END, got name '#{token}'" if name
+              name = token
+            when :type_next
+              raise SyntaxError, "expecting name, got '#{token}' at #{@scanner.pos}" if name.nil?
+              type = create_type(name) unless type
+              current_parsed_types << type
+              name = nil
+              type = nil
+            when :fixed_collection_start, :collection_start
+              name ||= "Array"
+              klass = token_type == :collection_start ? CollectionType : FixedCollectionType
+              type = klass.new(name, parse(until_tokens: [:fixed_collection_end, :collection_end, :parse_end]))
+            when :hash_collection_start
+              name ||= "Hash"
+              type = parse_hash_collection(name)
+            end
+
+            [finished, current_parsed_types]
+          end
+        end
+
+        private
+
+        # @return [Array<Type>]
+        def parse_with_handlers
           loop do
             found = false
             TOKENS.each do |token_type, match|
@@ -130,32 +220,67 @@ module YARD
               # rubocop:disable Lint/AssignmentInCondition
               next unless (match.nil? && @scanner.eos?) || (match && token = @scanner.scan(match))
               found = true
-              case token_type
-              when :type_name, :symbol
-                raise SyntaxError, "expecting END, got name '#{token}'" if name
-                name = token
-              when :type_next
-                raise SyntaxError, "expecting name, got '#{token}' at #{@scanner.pos}" if name.nil?
-                type = Type.new(name) unless type
-                types << type
-                type = nil
-                name = nil
-              when :fixed_collection_start, :collection_start
-                name ||= "Array"
-                klass = token_type == :collection_start ? CollectionType : FixedCollectionType
-                type = klass.new(name, parse)
-              when :hash_collection_start
-                name ||= "Hash"
-                type = HashCollectionType.new(name, parse, parse)
-              when :hash_collection_next, :hash_collection_end, :fixed_collection_end, :collection_end, :parse_end
-                raise SyntaxError, "expecting name, got '#{token}'" if name.nil?
-                type = Type.new(name) unless type
-                types << type
-                return types
-              end
+              # @type [Array<Type>]
+              finished, types = yield(token_type, token)
+              return types if finished
+              break
             end
             raise SyntaxError, "invalid character at #{@scanner.peek(1)}" unless found
           end
+          nil
+        end
+
+        def parse_hash_collection(name)
+          key_value_pairs = []
+          current_keys = []
+          finished = false
+
+          parse_with_handlers do |token_type, token|
+            case token_type
+            when :type_name
+              current_keys << create_type(token)
+            when :type_next
+              # Comma - continue collecting keys unless we just processed a value
+              # In that case, start a new key group
+            when :hash_collection_value
+              # => - current keys map to the next value(s)
+              raise SyntaxError, "no keys before =>" if current_keys.empty?
+              values = parse(until_tokens: [:hash_collection_value_end, :parse_end])
+              key_value_pairs << [current_keys, values]
+              current_keys = []
+            when :hash_collection_end, :parse_end
+              # End of hash
+              finished = true
+            when :whitespace
+              # Ignore whitespace
+            end
+
+            [finished, HashCollectionType.new(name, key_value_pairs)]
+          end
+        end
+
+        private
+
+        def create_type(name)
+          if name[0, 1] == ":" || (name[0, 1] =~ /['"]/ && name[-1, 1] =~ /['"]/)
+            LiteralType.new(name)
+          elsif name[0, 1] == "#"
+            DuckType.new(name)
+          else
+            Type.new(name)
+          end
+        end
+
+        private
+
+        def create_type(name)
+          if name[0, 1] == ":" || (name[0, 1] =~ /['"]/ && name[-1, 1] =~ /['"]/)
+            LiteralType.new(name)
+          elsif name[0, 1] == "#"
+            DuckType.new(name)
+          else
+            Type.new(name)
+          end
         end
       end
     end