docscribe 1.1.0 → 1.2.0

data/lib/docscribe/config/filtering.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Docscribe
+  class Config
+    # Decide whether a file path should be processed based on `filter.files`.
+    #
+    # File paths are matched relative to the current working directory when possible.
+    # Exclude rules win. If no include rules are configured, files are included by default.
+    #
+    # @param [String] path file path to test
+    # @raise [StandardError]
+    # @return [Boolean]
+    def process_file?(path)
+      files = raw.dig('filter', 'files') || {}
+      include_patterns = normalize_file_patterns(files['include'])
+      exclude_patterns = normalize_file_patterns(files['exclude'])
+
+      rel = begin
+        Pathname.new(path).relative_path_from(Pathname.pwd).to_s
+      rescue StandardError
+        path
+      end
+
+      return false if file_matches_any?(exclude_patterns, rel)
+      return true if include_patterns.empty?
+
+      file_matches_any?(include_patterns, rel)
+    end
+
+    # Decide whether a method should be processed based on configured method filters.
+    #
+    # Method IDs are normalized as:
+    # - instance method => `MyModule::MyClass#foo`
+    # - class method    => `MyModule::MyClass.foo`
+    #
+    # Exclude rules win. If no include rules are configured, methods are included by default
+    # subject to scope and visibility allow-lists.
+    #
+    # @param [String] container enclosing class/module name
+    # @param [Symbol] scope :instance or :class
+    # @param [Symbol] visibility :public, :protected, or :private
+    # @param [String, Symbol] name method name
+    # @return [Boolean]
+    def process_method?(container:, scope:, visibility:, name:)
+      return false unless filter_scopes.include?(scope.to_s)
+      return false unless filter_visibilities.include?(visibility.to_s)
+
+      method_id = "#{container}#{scope == :instance ? '#' : '.'}#{name}"
+
+      return false if matches_any?(filter_exclude_patterns, method_id)
+
+      inc = filter_include_patterns
+      return true if inc.empty?
+
+      matches_any?(inc, method_id)
+    end
+
+    private
+
+    # Normalize file filter patterns:
+    # - compact nils
+    # - stringify
+    # - remove empties
+    # - expand shorthand directory forms
+    #
+    # @private
+    # @param [Array<String>, nil] list raw pattern list
+    # @return [Array<String>]
+    def normalize_file_patterns(list)
+      Array(list).compact.map(&:to_s).reject(&:empty?).flat_map { |pat| expand_directory_shorthand(pat) }.uniq
+    end
+
+    # Expand a directory-like pattern into a recursive glob when appropriate.
+    #
+    # Examples:
+    # - `"spec/"` => `"spec/**/*"`
+    # - `"spec"` => `"spec/**/*"` if `spec` exists as a directory
+    #
+    # @private
+    # @param [String] pattern
+    # @return [Array<String>]
+    def expand_directory_shorthand(pattern)
+      pat = pattern.dup
+
+      if pat.end_with?('/')
+        ["#{pat}**/*"]
+      elsif !pat.match?(/[*?\[]|{/) && File.directory?(pat)
+        ["#{pat}/**/*"]
+      else
+        [pat]
+      end
+    end
+
+    # Check whether a file path matches any configured file pattern.
+    #
+    # @private
+    # @param [Array<String>] patterns
+    # @param [String] path
+    # @return [Boolean]
+    def file_matches_any?(patterns, path)
+      patterns.any? { |pat| file_match_pattern?(pat, path) }
+    end
+
+    # Match a file path against a single configured file filter.
+    #
+    # Supports:
+    # - `/regex/`
+    # - globs
+    # - recursive glob shorthand normalization
+    #
+    # @private
+    # @param [String] pattern
+    # @param [String] path
+    # @return [Boolean]
+    def file_match_pattern?(pattern, path)
+      if pattern.start_with?('/') && pattern.end_with?('/') && pattern.length >= 2
+        return Regexp.new(pattern[1..-2]).match?(path)
+      end
+
+      patterns_to_try = [pattern]
+      patterns_to_try << pattern.gsub('/**/', '/') if pattern.include?('/**/')
+
+      patterns_to_try.any? do |pat|
+        File.fnmatch?(pat, path, File::FNM_EXTGLOB | File::FNM_PATHNAME)
+      end
+    end
+
+    # Allowed method scopes from config/defaults.
+    #
+    # @private
+    # @return [Array<String>]
+    def filter_scopes
+      Array(raw.dig('filter', 'scopes') || DEFAULT.dig('filter', 'scopes')).map(&:to_s)
+    end
+
+    # Allowed method visibilities from config/defaults.
+    #
+    # @private
+    # @return [Array<String>]
+    def filter_visibilities
+      Array(raw.dig('filter', 'visibilities') || DEFAULT.dig('filter', 'visibilities')).map(&:to_s)
+    end
+
+    # Exclude method filter patterns.
+    #
+    # @private
+    # @return [Array<String>]
+    def filter_exclude_patterns
+      Array(raw.dig('filter', 'exclude') || DEFAULT.dig('filter', 'exclude')).map(&:to_s).reject(&:empty?)
+    end
+
+    # Include method filter patterns.
+    #
+    # @private
+    # @return [Array<String>]
+    def filter_include_patterns
+      Array(raw.dig('filter', 'include') || DEFAULT.dig('filter', 'include')).map(&:to_s).reject(&:empty?)
+    end
+  end
+end

data/lib/docscribe/config/loader.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Docscribe
+  class Config
+    # Load Docscribe configuration from YAML.
+    #
+    # Resolution order:
+    # - explicit `path`, if it exists
+    # - `docscribe.yml` in the current directory, if present
+    # - otherwise defaults only
+    #
+    # @param [String, nil] path optional config path
+    # @return [Docscribe::Config]
+    def self.load(path = nil)
+      raw = {}
+      if path && File.file?(path)
+        raw = safe_load_file_compat(path)
+      elsif File.file?('docscribe.yml')
+        raw = safe_load_file_compat('docscribe.yml')
+      end
+      new(raw)
+    end
+
+    # Safely load YAML from a file across Ruby/Psych versions.
+    #
+    # Uses `YAML.safe_load_file` when available, otherwise falls back to reading the file
+    # and calling {safe_load_compat}.
+    #
+    # @param [String] path file path
+    # @return [Hash]
+    def self.safe_load_file_compat(path)
+      if YAML.respond_to?(:safe_load_file)
+        YAML.safe_load_file(path, permitted_classes: [], permitted_symbols: [], aliases: true) || {}
+      else
+        yaml = File.open(path, 'r:bom|utf-8', &:read)
+        safe_load_compat(yaml, filename: path) || {}
+      end
+    end
+
+    # Safely load YAML from a string across Psych API versions.
+    #
+    # @param [String] yaml YAML document
+    # @param [String, nil] filename optional filename for diagnostics
+    # @raise [ArgumentError]
+    # @return [Hash]
+    def self.safe_load_compat(yaml, filename: nil)
+      Psych.safe_load(
+        yaml,
+        permitted_classes: [],
+        permitted_symbols: [],
+        aliases: true,
+        filename: filename
+      )
+    rescue ArgumentError
+      # Older Psych signature uses positional args
+      Psych.safe_load(yaml, [], [], true, filename)
+    end
+  end
+end

data/lib/docscribe/config/rbs.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Docscribe
+  class Config
+    # Return a memoized RBS provider if RBS integration is enabled and available.
+    #
+    # If RBS cannot be loaded, this returns nil and Docscribe falls back to
+    # inference.
+    #
+    # @raise [LoadError]
+    # @return [Docscribe::Types::RBS::Provider, nil]
+    def rbs_provider
+      return nil unless rbs_enabled?
+
+      @rbs_provider ||= begin
+        require 'docscribe/types/rbs/provider'
+        Docscribe::Types::RBS::Provider.new(
+          sig_dirs: rbs_sig_dirs,
+          collapse_generics: rbs_collapse_generics?
+        )
+      rescue LoadError
+        nil
+      end
+    end
+
+    # Whether RBS integration is enabled.
+    #
+    # @return [Boolean]
+    def rbs_enabled?
+      fetch_bool(%w[rbs enabled], false)
+    end
+
+    # Signature directories used by the RBS provider.
+    #
+    # @return [Array<String>]
+    def rbs_sig_dirs
+      Array(raw.dig('rbs', 'sig_dirs') || DEFAULT.dig('rbs', 'sig_dirs')).map(&:to_s)
+    end
+
+    # Whether generic RBS types should be collapsed to simpler container names.
+    #
+    # Examples:
+    # - `Hash<Symbol, String>` => `Hash`
+    # - `Array<Integer>`       => `Array`
+    #
+    # @return [Boolean]
+    def rbs_collapse_generics?
+      fetch_bool(%w[rbs collapse_generics], false)
+    end
+  end
+end

data/lib/docscribe/config/sorbet.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Docscribe
+  class Config
+    # Build the effective external signature provider chain for a given source.
+    #
+    # Provider precedence is:
+    # 1. inline Sorbet signatures from the current source
+    # 2. Sorbet RBI files
+    # 3. RBS files
+    #
+    # Returns nil when no external type provider is enabled or available.
+    #
+    # @param [String] source Ruby source being rewritten
+    # @param [String] file source name for diagnostics
+    # @raise [LoadError]
+    # @return [Docscribe::Types::ProviderChain, nil]
+    def signature_provider_for(source:, file:)
+      providers = []
+
+      if sorbet_enabled?
+        begin
+          require 'docscribe/types/sorbet/source_provider'
+          providers << Docscribe::Types::Sorbet::SourceProvider.new(
+            source: source,
+            file: file,
+            collapse_generics: sorbet_collapse_generics?
+          )
+        rescue LoadError
+          # Sorbet support is optional; fall back quietly.
+        end
+
+        providers << sorbet_rbi_provider
+      end
+
+      providers << rbs_provider if rbs_enabled?
+
+      providers = providers.compact
+      return nil if providers.empty?
+
+      require 'docscribe/types/provider_chain'
+      Docscribe::Types::ProviderChain.new(*providers)
+    end
+
+    # Return a memoized Sorbet RBI provider if Sorbet integration is enabled.
+    #
+    # @raise [LoadError]
+    # @return [Docscribe::Types::Sorbet::RBIProvider, nil]
+    def sorbet_rbi_provider
+      return nil unless sorbet_enabled?
+
+      @sorbet_rbi_provider ||= begin
+        require 'docscribe/types/sorbet/rbi_provider'
+        Docscribe::Types::Sorbet::RBIProvider.new(
+          rbi_dirs: sorbet_rbi_dirs,
+          collapse_generics: sorbet_collapse_generics?
+        )
+      rescue LoadError
+        nil
+      end
+    end
+
+    # Whether Sorbet support is enabled in config.
+    #
+    # @return [Boolean]
+    def sorbet_enabled?
+      fetch_bool(%w[sorbet enabled], false)
+    end
+
+    # RBI directories searched by the Sorbet provider.
+    #
+    # @return [Array<String>]
+    def sorbet_rbi_dirs
+      Array(raw.dig('sorbet', 'rbi_dirs') || DEFAULT.dig('sorbet', 'rbi_dirs')).map(&:to_s)
+    end
+
+    # Whether generic Sorbet/RBI container types should be simplified.
+    #
+    # Falls back to the RBS `collapse_generics` setting when Sorbet-specific
+    # config is not present.
+    #
+    # @return [Boolean]
+    def sorbet_collapse_generics?
+      fetch_bool(%w[sorbet collapse_generics], rbs_collapse_generics?)
+    end
+  end
+end

data/lib/docscribe/config/sorting.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Docscribe
+  class Config
+    # Whether sortable tag normalization is enabled for doc-like blocks.
+    #
+    # @return [Boolean]
+    def sort_tags?
+      raw.dig('doc', 'sort_tags') != false
+    end
+
+    # Configured sortable tag order.
+    #
+    # Tags are normalized without a leading `@`.
+    #
+    # @return [Array<String>]
+    def tag_order
+      Array(raw.dig('doc', 'tag_order') || DEFAULT.dig('doc', 'tag_order')).map do |t|
+        t.to_s.sub(/\A@/, '')
+      end
+    end
+  end
+end

data/lib/docscribe/config/template.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+module Docscribe
+  class Config
+    # Return the default YAML template used by `docscribe init`.
+    #
+    # The template documents the most common CLI workflows and all supported
+    # configuration sections with comments.
+    # @see Docscribe::Config::DEFAULT
+    #
+    # @return [String]
+    def self.default_yaml
+      <<~YAML
+        ---
+        # Docscribe configuration file
+        #
+        # Inspect what safe doc updates would be applied:
+        #   bundle exec docscribe lib
+        #
+        # Apply safe doc updates:
+        #   bundle exec docscribe -a lib
+        #
+        # Apply aggressive doc updates (rebuild existing doc blocks):
+        #   bundle exec docscribe -A lib
+        #
+
+        emit:
+          # Emit the header line:
+          #
+          #   +MyClass#my_method+ -> ReturnType
+          header: true
+
+          # Emit @param tags.
+          param_tags: true
+
+          # Emit @return tag (can be overridden per scope/visibility under methods:).
+          return_tag: true
+
+          # Emit @private / @protected tags based on Ruby visibility context.
+          visibility_tags: true
+
+          # Emit @raise tags inferred from rescue clauses / raise/fail calls.
+          raise_tags: true
+
+          # Emit conditional rescue return tags:
+          #
+          #   @return [String] if FooError, BarError
+          rescue_conditional_returns: true
+
+          # Generate @!attribute docs for attr_reader/attr_writer/attr_accessor.
+          attributes: false
+
+        doc:
+          # Default text inserted into each generated doc block.
+          default_message: "Method documentation."
+
+          # Default text appended to generated @param tags.
+          param_documentation: "Param documentation."
+
+          # Style for generated @param tags:
+          # - type_name => @param [Type] name
+          # - name_type => @param name [Type]
+          param_tag_style: "type_name"
+
+          # Sort generated / merged tags in safe mode when possible.
+          sort_tags: true
+
+          # Tag order used when sorting contiguous tag runs.
+          tag_order: ["todo", "note", "api", "private", "protected", "param", "option", "yieldparam", "raise", "return"]
+
+        methods:
+          # Per-scope / per-visibility overrides.
+          #
+          # Example:
+          # methods:
+          #   instance:
+          #     public:
+          #       default_message: "Public API."
+          #       return_tag: true
+          instance:
+            public: {}
+            protected: {}
+            private: {}
+
+          class:
+            public: {}
+            protected: {}
+            private: {}
+
+        inference:
+          # Type used when inference is uncertain.
+          fallback_type: "Object"
+
+          # Whether nil unions become optional types (for example String | nil => String?).
+          nil_as_optional: true
+
+          # Special-case: treat keyword arg named options/options: as a Hash.
+          treat_options_keyword_as_hash: true
+
+        filter:
+          # Filter which methods Docscribe touches.
+          #
+          # Method id format:
+          #   instance: "MyModule::MyClass#instance_method"
+          #   class:    "MyModule::MyClass.class_method"
+          #
+          # Patterns:
+          # - glob: "*#initialize", "MyApp::*#*"
+          # - regex: "/^MyApp::.*#(foo|bar)$/"
+          #
+          # Semantics:
+          # - scopes / visibilities act as allow-lists
+          # - exclude wins
+          # - if include is empty => include everything (subject to allow-lists)
+          visibilities: ["public", "protected", "private"]
+          scopes: ["instance", "class"]
+          include: []
+          exclude: []
+
+          files:
+            # Filter which files Docscribe processes (paths are matched relative
+            # to the project root).
+            #
+            # Tips:
+            # - Use directory shorthand to exclude a whole directory:
+            #     exclude: ["spec"]
+            # - Or use globs:
+            #     exclude: ["spec/**/*.rb", "vendor/**/*.rb"]
+            include: []
+            exclude: ["spec"]
+
+        rbs:
+          # Optional: use RBS signatures to improve @param / @return types.
+          #
+          # CLI equivalent:
+          # bundle exec docscribe -a --rbs --sig-dir sig lib
+          #
+          # Under Bundler, you may need `gem "rbs"` in your Gemfile (or a
+          # Gemfile that includes it), otherwise `require "rbs"` may fail and
+          # Docscribe will fall back to inference.
+          enabled: false
+
+          # Signature directories (repeatable via --sig-dir).
+          sig_dirs: ["sig"]
+
+          # If true, simplify generic types:
+          # - Hash<Symbol, String> => Hash
+          # - Array<Integer>       => Array
+          collapse_generics: false
+
+        sorbet:
+          # Optional: use Sorbet signatures from inline `sig` declarations and
+          # RBI files to improve @param / @return types.
+          #
+          # CLI equivalent:
+          # bundle exec docscribe -a --sorbet --rbi-dir sorbet/rbi lib
+          #
+          # Sorbet resolution order is:
+          # 1. inline `sig` in the current source file
+          # 2. RBI files
+          # 3. RBS
+          # 4. AST inference
+          enabled: false
+
+          # RBI directories scanned recursively for `.rbi` files
+          # (repeatable via --rbi-dir).
+          rbi_dirs: ["sorbet/rbi", "rbi"]
+
+          # If true, simplify generic types:
+          # - Hash<Symbol, String> => Hash
+          # - Array<Integer>       => Array
+          collapse_generics: false
+      YAML
+    end
+  end
+end

data/lib/docscribe/config/utils.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+module Docscribe
+  class Config
+    private
+
+    # Fetch a boolean method-level override for a given scope/visibility pair.
+    #
+    # @private
+    # @param [Symbol] scope :instance or :class
+    # @param [Symbol] vis :public, :protected, or :private
+    # @param [String] key override key
+    # @param [Boolean] default fallback value
+    # @return [Boolean]
+    def method_override_bool(scope, vis, key, default:)
+      node = raw.dig('methods', scope_to_key(scope), vis.to_s, key)
+      node.nil? ? default : !!node
+    end
+
+    # Fetch a string method-level override for a given scope/visibility pair.
+    #
+    # @private
+    # @param [Symbol] scope :instance or :class
+    # @param [Symbol] vis :public, :protected, or :private
+    # @param [String] key override key
+    # @param [String] default fallback value
+    # @return [String]
+    def method_override_str(scope, vis, key, default:)
+      node = raw.dig('methods', scope_to_key(scope), vis.to_s, key)
+      node.nil? ? default : node.to_s
+    end
+
+    # Fetch a boolean config value by nested path with a default fallback.
+    #
+    # @private
+    # @param [Array<String>] path nested config keys
+    # @param [Boolean] default fallback value
+    # @return [Boolean]
+    def fetch_bool(path, default)
+      node = raw
+      path.each { |k| node = node[k] if node }
+      node.nil? ? default : !!node
+    end
+
+    # Convert an internal scope symbol into the config key used under `methods`.
+    #
+    # @private
+    # @param [Symbol] scope
+    # @return [String]
+    def scope_to_key(scope)
+      scope == :class ? 'class' : 'instance'
+    end
+
+    # Check whether any pattern matches the given text.
+    #
+    # @private
+    # @param [Array<String>] patterns
+    # @param [String] text
+    # @return [Boolean]
+    def matches_any?(patterns, text)
+      patterns.any? { |pat| match_pattern?(pat, text) }
+    end
+
+    # Match a method filter pattern against a method ID.
+    #
+    # Supports:
+    # - `/regex/`
+    # - shell-style glob patterns
+    #
+    # @private
+    # @param [String] pattern
+    # @param [String] text
+    # @return [Boolean]
+    def match_pattern?(pattern, text)
+      if pattern.start_with?('/') && pattern.end_with?('/') && pattern.length >= 2
+        Regexp.new(pattern[1..-2]).match?(text)
+      else
+        File.fnmatch?(pattern, text, File::FNM_EXTGLOB)
+      end
+    end
+
+    # Deep-merge two hashes, preferring values from the second hash.
+    #
+    # Nested hashes are merged recursively; non-hash values are replaced.
+    #
+    # @private
+    # @param [Hash] hash1 base hash
+    # @param [Hash, nil] hash2 override hash
+    # @return [Hash]
+    def deep_merge(hash1, hash2)
+      return hash1 unless hash2
+
+      hash1.merge(hash2) do |_, v1, v2|
+        if v1.is_a?(Hash) && v2.is_a?(Hash)
+          deep_merge(v1, v2)
+        else
+          v2
+        end
+      end
+    end
+  end
+end