Fixed bug while parsing standalone def structures

Author: unurgunite

.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-03-28 07:58:29 UTC using RuboCop version 1.84.0.
+# on 2026-04-12 12:42:12 UTC using RuboCop version 1.84.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -32,7 +32,7 @@ Metrics/BlockNesting:
 # Offense count: 4
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ClassLength:
-  Max: 393
+  Max: 407
 
 # Offense count: 30
 # Configuration parameters: AllowedMethods, AllowedPatterns.
@@ -42,12 +42,12 @@ Metrics/CyclomaticComplexity:
 # Offense count: 65
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 110
+  Max: 105
 
 # Offense count: 6
 # Configuration parameters: CountComments, CountAsOne.
 Metrics/ModuleLength:
-  Max: 403
+  Max: 398
 
 # Offense count: 9
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
@@ -77,7 +77,7 @@ Naming/PredicateMethod:
   Exclude:
     - 'lib/docscribe/inline_rewriter/collector.rb'
 
-# Offense count: 60
+# Offense count: 61
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -87,17 +87,16 @@ RSpec/DescribeClass:
 RSpec/ExampleLength:
   Max: 33
 
-# Offense count: 125
+# Offense count: 128
 RSpec/MultipleExpectations:
   Max: 7
 
-# Offense count: 14
+# Offense count: 13
 # Configuration parameters: AllowedConstants.
 Style/Documentation:
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
-    - 'abc.rb'
     - 'lib/docscribe/cli.rb'
     - 'lib/docscribe/cli/config_builder.rb'
     - 'lib/docscribe/cli/init.rb'

Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    docscribe (1.2.1)
+    docscribe (1.3.0)
       parser (>= 3.3)
       prism (~> 1.8)
 
@@ -85,7 +85,7 @@ DEPENDENCIES
 CHECKSUMS
   ast (2.4.3) sha256=954615157c1d6a382bc27d690d973195e79db7f55e9765ac7c481c60bdb4d383
   diff-lcs (1.6.2) sha256=9ae0d2cba7d4df3075fe8cd8602a8604993efc0dfa934cff568969efb1909962
-  docscribe (1.2.1)
+  docscribe (1.3.0)
   json (2.18.0) sha256=b10506aee4183f5cf49e0efc48073d7b75843ce3782c68dbeb763351c08fd505
   language_server-protocol (3.17.0.5) sha256=fd1e39a51a28bf3eec959379985a72e296e9f9acfce46f6a79d31ca8760803cc
   lint_roller (1.1.0) sha256=2c0c845b632a7d172cb849cc90c1bce937a28c5c8ccccb50dfd46a485003cc87

Gemfile_2_7.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    docscribe (1.2.1)
+    docscribe (1.3.0)
       parser (>= 3.3)
       prism (~> 1.8)
 
@@ -65,6 +65,7 @@ GEM
     yard (0.9.38)
 
 PLATFORMS
+  arm64-darwin-24
   arm64-darwin-25
   x86_64-linux
 

lib/docscribe/inline_rewriter/collector.rb

@@ -240,6 +240,39 @@ def on_casgn(node)
         node
       end
 
+      # Enter a top-level method definition and collect it as a documentation target.
+      #
+      # Top-level methods implicitly belong to +Object+. This handler ensures
+      # that +def foo+ declared outside of any class or module is still picked
+      # up by the collector.
+      #
+      # @param [Parser::AST::Node] node
+      # @return [Parser::AST::Node]
+      def on_def(node)
+        return node unless @name_stack.empty?
+
+        ctx = VisibilityCtx.new
+        ctx.container_is_module = false
+        process_stmt(node, ctx)
+        node
+      end
+
+      # Enter a top-level singleton method definition and collect it as a documentation target.
+      #
+      # Handles the case of +def self.foo+ declared at the top level, outside
+      # of any class or module body.
+      #
+      # @param [Parser::AST::Node] node
+      # @return [Parser::AST::Node]
+      def on_defs(node)
+        return node unless @name_stack.empty?
+
+        ctx = VisibilityCtx.new
+        ctx.container_is_module = false
+        process_stmt(node, ctx)
+        node
+      end
+
       private
 
       # Method documentation.

lib/docscribe/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Docscribe
-  VERSION = '1.2.1'
+  VERSION = '1.3.0'
 end

spec/strategies/safe/top_level_spec.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+RSpec.describe 'top-level methods' do
+  subject(:out) { Docscribe::InlineRewriter.insert_comments(code, strategy: :safe, config: conf) }
+
+  let(:conf) { Docscribe::Config.new('emit' => { 'header' => true }) }
+
+  context 'when a method is defined outside any class or module' do
+    let(:code) { <<~RUBY }
+      def foo
+        1
+      end
+    RUBY
+
+    it 'adds documentation' do
+      expect(out).to include('Object#foo')
+      expect(out).to include('# Method documentation.')
+    end
+  end
+
+  context 'when a singleton method is defined at top level' do
+    let(:code) { <<~RUBY }
+      def self.bar
+        2
+      end
+    RUBY
+
+    it 'adds documentation' do
+      expect(out).to include('Object.bar')
+      expect(out).to include('# Method documentation.')
+    end
+  end
+
+  context 'when top-level and class methods coexist' do
+    let(:code) { <<~RUBY }
+      def foo
+        1
+      end
+
+      class Obj
+        def abc(param: {})
+          12
+        end
+      end
+    RUBY
+
+    it 'documents both' do
+      expect(out).to include('# +Object#foo+')
+      expect(out).to include('# +Obj#abc+')
+    end
+  end
+end