docscribe 1.4.1 → 1.5.0

data/lib/docscribe/parsing.rb

@@ -36,20 +36,31 @@ module Docscribe
 
       # Parse a prepared source buffer into a parser-gem-compatible AST.
       #
-      # @param [Parser::Source::Buffer] buffer
+      # Returns +nil+ when the source cannot be parsed (syntax errors or
+      # internal parser crashes).
+      #
+      # @param [Parser::Source::Buffer] buffer prepared source buffer
       # @param [Symbol] backend :auto, :parser, or :prism
-      # @return [Parser::AST::Node, nil]
+      # @raise [NoMethodError]
+      # @return [Parser::AST::Node, nil] if NoMethodError
+      # @return [nil] if NoMethodError
       def parse_buffer(buffer, backend: :auto)
         parser = parser_for(backend: backend)
+        return nil unless parser
+
         parser.parse(buffer)
+      rescue NoMethodError
+        nil
       end
 
       # Parse source code and also return comments when supported by the backend.
       #
+      # Returns +nil+ when the source cannot be parsed.
+      #
       # @param [String] code Ruby source
       # @param [String] file source name used for parser locations
       # @param [Symbol] backend :auto, :parser, or :prism
-      # @return [Array<(Parser::AST::Node, Array)>]
+      # @return [(Parser::AST::Node?, Array<Parser::Source::Comment>), nil]
       def parse_with_comments(code, file: '(docscribe)', backend: :auto)
         buffer = Parser::Source::Buffer.new(file, source: code)
         parse_with_comments_buffer(buffer, backend: backend)
@@ -57,12 +68,20 @@ module Docscribe
 
       # Parse a prepared source buffer and also return comments when supported by the backend.
       #
-      # @param [Parser::Source::Buffer] buffer
+      # Returns +nil+ when the source cannot be parsed.
+      #
+      # @param [Parser::Source::Buffer] buffer prepared source buffer
       # @param [Symbol] backend :auto, :parser, or :prism
-      # @return [Array<(Parser::AST::Node, Array)>]
+      # @raise [NoMethodError]
+      # @return [(Parser::AST::Node?, Array<Parser::Source::Comment>), nil] if NoMethodError
+      # @return [nil] if NoMethodError
       def parse_with_comments_buffer(buffer, backend: :auto)
         parser = parser_for(backend: backend)
+        return nil unless parser
+
         parser.parse_with_comments(buffer)
+      rescue NoMethodError
+        nil
       end
 
       private
@@ -70,16 +89,16 @@ module Docscribe
       # Build the backend-specific parser object.
       #
       # @private
-      # @param [Symbol] backend
-      # @return [Object]
+      # @param [Symbol] backend requested backend
+      # @return [Parser::Base, nil]
       def parser_for(backend: :auto)
         case backend(backend)
         when :parser
           require 'parser/current'
-          Parser::CurrentRuby.new
+          Parser::CurrentRuby.new # steep:ignore
         when :prism
           require 'prism'
-          Prism::Translation::ParserCurrent.new
+          Prism::Translation::ParserCurrent.new # steep:ignore
         end
       end
 
@@ -93,7 +112,7 @@ module Docscribe
       # @private
       # @param [Symbol] backend requested backend
       # @raise [ArgumentError]
-      # @return [Symbol] :parser or :prism
+      # @return [Symbol, nil] :parser or :prism
       def backend(backend = :auto)
         env = ENV.fetch('DOCSCRIBE_PARSER_BACKEND') { nil }
         backend = env.to_sym if env && !env.empty?

data/lib/docscribe/plugin/base/collector_plugin.rb

@@ -41,9 +41,9 @@ module Docscribe
         # - :anchor_node => Parser::AST::Node — node above which to insert doc
         # - :doc         => String — complete doc block including newlines
         #
-        # @param [Object] _ast Param documentation.
-        # @param [Object] _buffer Param documentation.
-        # @return [Array<Hash>]
+        # @param [Parser::AST::Node] _ast AST node to analyze
+        # @param [Parser::Source::Buffer] _buffer source buffer
+        # @return [Array<Hash<Symbol, Object>>]
         def collect(_ast, _buffer)
           []
         end

data/lib/docscribe/plugin/base/tag_plugin.rb

@@ -26,8 +26,7 @@ module Docscribe
         # Called once per documented method. Return [] if this plugin has
         # nothing to add for this particular method.
         #
-        # @param [Docscribe::Plugin::Context] context method context snapshot
-        # @param [Object] _context Param documentation.
+        # @param [Docscribe::Plugin::Context] _context method context snapshot (unused in default)
         # @return [Array<Docscribe::Plugin::Tag>]
         def call(_context)
           []

data/lib/docscribe/plugin/context.rb

@@ -2,27 +2,37 @@
 
 module Docscribe
   module Plugin
-    # Snapshot of everything known about a method at doc-generation time.
+    # @!attribute [rw] node
+    #   @return [Parser::AST::Node]
+    #   @param [Parser::AST::Node] value
     #
-    # Passed to every registered TagPlugin. Read-only — plugins must not
-    # mutate the context.
+    # @!attribute [rw] container
+    #   @return [String]
+    #   @param [String] value
     #
-    # @!attribute node
-    #   @return [Parser::AST::Node] the :def or :defs AST node
-    # @!attribute container
-    #   @return [String] e.g. "MyModule::MyClass" or "Object" for top-level
-    # @!attribute scope
-    #   @return [Symbol] :instance or :class
-    # @!attribute visibility
-    #   @return [Symbol] :public, :protected, or :private
-    # @!attribute method_name
+    # @!attribute [rw] scope
     #   @return [Symbol]
-    # @!attribute inferred_params
-    #   @return [Hash{String => String}] name => inferred type
-    # @!attribute inferred_return
-    #   @return [String] inferred return type
-    # @!attribute source
-    #   @return [String] raw method source text
+    #   @param [Symbol] value
+    #
+    # @!attribute [rw] visibility
+    #   @return [Symbol]
+    #   @param [Symbol] value
+    #
+    # @!attribute [rw] method_name
+    #   @return [Symbol]
+    #   @param [Symbol] value
+    #
+    # @!attribute [rw] inferred_params
+    #   @return [Hash<String, String>]
+    #   @param [Hash<String, String>] value
+    #
+    # @!attribute [rw] inferred_return
+    #   @return [String]
+    #   @param [String] value
+    #
+    # @!attribute [rw] source
+    #   @return [String]
+    #   @param [String] value
     Context = Struct.new(
       :node,
       :container,

data/lib/docscribe/plugin/registry.rb

@@ -16,12 +16,12 @@ module Docscribe
       #   @param [Object] value
       #
       # @!attribute [rw] priority
-      #   @return [Object]
-      #   @param [Object] value
+      #   @return [Integer]
+      #   @param [Integer] value
       #
       # @!attribute [rw] order
-      #   @return [Object]
-      #   @param [Object] value
+      #   @return [Integer]
+      #   @param [Integer] value
       Entry = Struct.new(:plugin, :priority, :order, keyword_init: true)
 
       @tag_entries = []
@@ -38,23 +38,49 @@ module Docscribe
       # - responds to #call                 => tag plugin (duck typing)
       # - responds to #collect              => collector plugin (duck typing)
       #
-      # @note module_function: when included, also defines #register (instance visibility: private)
+      # @note module_function: defines #register (visibility: private)
       # @param [Object] plugin plugin instance
       # @param [Integer] priority plugin priority (higher wins for conflicts)
-      # @raise [ArgumentError] if plugin type cannot be determined
-      # @raise [StandardError]
       # @return [void]
       def register(plugin, priority: 0)
-        prio =
-          begin
-            Integer(priority)
-          rescue StandardError
-            raise ArgumentError, "priority must be an Integer-like value, got: #{priority.inspect}"
-          end
+        prio = parse_priority(priority)
+        entry = create_entry(plugin, prio)
+        route_entry(entry, plugin)
+      end
 
+      # Parse and validate plugin priority.
+      #
+      # @note module_function: defines #parse_priority (visibility: private)
+      # @param [String, Integer] priority plugin priority (higher wins for conflicts)
+      # @raise [StandardError]
+      # @raise [ArgumentError]
+      # @return [Integer] if StandardError
+      # @return [Object] if StandardError
+      def parse_priority(priority)
+        Integer(priority)
+      rescue StandardError
+        raise ArgumentError, "priority must be an Integer-like value, got: #{priority.inspect}"
+      end
+
+      # Create a new Entry with the next order number.
+      #
+      # @note module_function: defines #create_entry (visibility: private)
+      # @param [Object] plugin plugin instance
+      # @param [Integer] priority plugin priority (higher wins for conflicts)
+      # @return [Docscribe::Plugin::Registry::Entry]
+      def create_entry(plugin, priority)
         @order_seq += 1
-        entry = Entry.new(plugin: plugin, priority: prio, order: @order_seq)
+        Entry.new(plugin: plugin, priority: priority, order: @order_seq)
+      end
 
+      # Route entry to tag or collector list.
+      #
+      # @note module_function: defines #route_entry (visibility: private)
+      # @param [Docscribe::Plugin::Registry::Entry] entry the entry to route
+      # @param [Object] plugin plugin instance
+      # @raise [ArgumentError]
+      # @return [void]
+      def route_entry(entry, plugin)
         if plugin.is_a?(Base::CollectorPlugin) || plugin.respond_to?(:collect)
           @collector_entries << entry
         elsif plugin.is_a?(Base::TagPlugin) || plugin.respond_to?(:call)
@@ -66,32 +92,32 @@ module Docscribe
 
       # All registered tag plugins in registration order.
       #
-      # @note module_function: when included, also defines #tag_plugins (instance visibility: private)
-      # @return [Array<#call>]
+      # @note module_function: defines #tag_plugins (visibility: private)
+      # @return [Array<Object>]
       def tag_plugins
         @tag_entries.map(&:plugin)
       end
 
       # All registered collector plugins in registration order.
       #
-      # @note module_function: when included, also defines #collector_plugins (instance visibility: private)
-      # @return [Array<#collect>]
+      # @note module_function: defines #collector_plugins (visibility: private)
+      # @return [Array<Object>]
       def collector_plugins
         @collector_entries.map(&:plugin)
       end
 
       # All registered tag plugin entries (plugin + priority metadata).
       #
-      # @note module_function: when included, also defines #tag_entries (instance visibility: private)
-      # @return [Array<Entry>]
+      # @note module_function: defines #tag_entries (visibility: private)
+      # @return [Array<Docscribe::Plugin::Registry::Entry>]
       def tag_entries
         @tag_entries.dup
       end
 
       # All registered collector plugin entries (plugin + priority metadata).
       #
-      # @note module_function: when included, also defines #collector_entries (instance visibility: private)
-      # @return [Array<Entry>]
+      # @note module_function: defines #collector_entries (visibility: private)
+      # @return [Array<Docscribe::Plugin::Registry::Entry>]
       def collector_entries
         @collector_entries.dup
       end
@@ -100,7 +126,7 @@ module Docscribe
       #
       # Primarily used in tests to reset state between examples.
       #
-      # @note module_function: when included, also defines #clear! (instance visibility: private)
+      # @note module_function: defines #clear! (visibility: private)
       # @return [void]
       def clear!
         @tag_entries.clear

data/lib/docscribe/plugin/tag.rb

@@ -2,22 +2,17 @@
 
 module Docscribe
   module Plugin
-    # A single YARD-style tag returned by a TagPlugin.
+    # @!attribute [rw] name
+    #   @return [String]
+    #   @param [String] value
     #
-    # @example Simple tag
-    #   Tag.new(name: 'since', text: '1.3.0')
-    #   # => # @since 1.3.0
+    # @!attribute [rw] text
+    #   @return [String, nil]
+    #   @param [String, nil] value
     #
-    # @example Tag with types
-    #   Tag.new(name: 'raise', types: ['ArgumentError'], text: 'if name is nil')
-    #   # => # @raise [ArgumentError] if name is nil
-    #
-    # @!attribute name
-    #   @return [String] tag name without leading @
-    # @!attribute text
-    #   @return [String, nil] text after the type bracket
-    # @!attribute types
-    #   @return [Array<String>, nil] optional type list rendered as [Foo, Bar]
+    # @!attribute [rw] types
+    #   @return [Array<String>, nil]
+    #   @param [Array<String>, nil] value
     Tag = Struct.new(:name, :text, :types, keyword_init: true)
   end
 end

data/lib/docscribe/plugin.rb

@@ -23,7 +23,7 @@ module Docscribe
     # Errors in individual plugins are caught so one broken plugin does not
     # abort the entire run.
     #
-    # @param [Docscribe::Plugin::Context] context
+    # @param [Docscribe::Plugin::Context] context plugin execution context
     # @raise [StandardError]
     # @return [Array<Docscribe::Plugin::Tag>]
     def self.run_tag_plugins(context)
@@ -43,32 +43,64 @@ module Docscribe
 
     # Run all registered CollectorPlugins for one file's AST.
     #
-    # @param [Parser::AST::Node] ast
-    # @param [Parser::Source::Buffer] buffer
-    # @raise [StandardError]
-    # @return [Array<Hash>]
+    # @param [Parser::AST::Node] ast parsed AST root node
+    # @param [Parser::Source::Buffer] buffer source buffer for AST
+    # @return [Array<Hash<Symbol, Object>>]
     def self.run_collector_plugins(ast, buffer)
-      Registry.collector_entries.flat_map do |entry|
-        plugin = entry.plugin
+      Registry.collector_entries.flat_map { |entry| process_single_plugin_result(entry, ast, buffer) }
+    end
 
-        Array(plugin.collect(ast, buffer)).map do |insertion|
-          unless insertion.is_a?(Hash)
-            warn "Docscribe: CollectorPlugin #{plugin.class} returned #{insertion.class}, expected Hash" if debug?
-            next nil
-          end
+    # Process a single collector plugin's result.
+    #
+    # Merges plugin metadata into each hash insertion and handles errors.
+    #
+    # @param [Docscribe::Plugin::Registry::Entry] entry registry entry with priority and order metadata
+    # @param [Parser::AST::Node] ast parsed AST root node
+    # @param [Parser::Source::Buffer] buffer source buffer for AST
+    # @raise [StandardError]
+    # @return [Array<Hash<Symbol, Object>>] if StandardError
+    # @return [Array] if StandardError
+    def self.process_single_plugin_result(entry, ast, buffer)
+      plugin = entry.plugin
+      results = Array(plugin.collect(ast, buffer))
+      process_plugin_insertions(results, entry, plugin)
+    rescue StandardError => e
+      warn "Docscribe: CollectorPlugin #{plugin.class} raised #{e.class}: #{e.message}" if debug?
+      []
+    end
 
-          insertion.merge(
-            __docscribe_priority: entry.priority,
-            __docscribe_plugin_class: plugin.class.name,
-            __docscribe_plugin_order: entry.order
-          )
-        end.compact
-      rescue StandardError => e
-        warn "Docscribe: CollectorPlugin #{plugin.class} raised #{e.class}: #{e.message}" if debug?
-        []
-      end
+    # Merge plugin metadata into collector results and filter invalid ones.
+    #
+    # @param [Array<Hash<Symbol, Object>>] results collector plugin results to process
+    # @param [Docscribe::Plugin::Registry::Entry] entry registry entry with priority and order metadata
+    # @param [Object] plugin the collector plugin instance
+    # @return [Array<Hash<Symbol, Object>>]
+    def self.process_plugin_insertions(results, entry, plugin)
+      results.map do |insertion|
+        next nil unless valid_plugin_result?(insertion, plugin)
+
+        insertion.merge(
+          __docscribe_priority: entry.priority,
+          __docscribe_plugin_class: plugin.class.name,
+          __docscribe_plugin_order: entry.order
+        )
+      end.compact
     end
 
+    # Validate a CollectorPlugin result is a Hash.
+    #
+    # @param [Object] insertion collector plugin result
+    # @param [Object] plugin the collector plugin instance
+    # @return [Boolean]
+    def self.valid_plugin_result?(insertion, plugin)
+      return true if insertion.is_a?(Hash)
+
+      warn "Docscribe: CollectorPlugin #{plugin.class} returned #{insertion.class}, expected Hash" if debug?
+      false
+    end
+
+    # Self
+    #
     # @return [Boolean]
     def self.debug?
       ENV['DOCSCRIBE_DEBUG'] == '1'

data/lib/docscribe/types/provider_chain.rb

@@ -12,8 +12,10 @@ module Docscribe
     # - Sorbet RBI files
     # - RBS files
     class ProviderChain
-      # @param [Array<#signature_for>] providers ordered signature providers
-      # @return [Object]
+      # Initialize
+      #
+      # @param [Array<Docscribe::Types::_Provider>] providers ordered signature providers
+      # @return [void]
       def initialize(*providers)
         @providers = providers.compact
       end

data/lib/docscribe/types/rbs/collection_loader.rb

@@ -1,4 +1,3 @@
-# lib/docscribe/types/rbs/collection_loader.rb
 # frozen_string_literal: true
 
 require 'pathname'
@@ -31,14 +30,14 @@ module Docscribe
         # - lock-file is absent (collection not initialized)
         # - resolved directory does not exist on disk (collection not installed)
         #
-        # @note module_function: when included, also defines #resolve (instance visibility: private)
+        # @note module_function: defines #resolve (visibility: private)
         # @param [String] root project root to search from
         # @return [String, nil] absolute path to the collection directory, or nil
         def resolve(root: Dir.pwd)
           lock = Pathname(root).join(LOCK_FILE)
           return nil unless lock.file?
 
-          data = YAML.safe_load(lock.read, permitted_classes: [Symbol]) || {}
+          data = YAML.safe_load(lock.read, permitted_classes: [Symbol]) || {} # steep:ignore
           rel  = data['path'] || DEFAULT_COLLECTION_PATH
 
           resolved = Pathname(root).join(rel)