Fix NoMethodError when processing empty files (#232)

## Summary

This PR fixes issue #182 where `annotaterb models --force` fails with a
`NoMethodError: undefined method '+' for nil` when processing empty
model files or files that contain no classes/modules.

## Problem Description

When `annotaterb` encounters an empty file or a file with only
comments/whitespace:

1. The file parser returns empty arrays for `parsed.starts` and
`parsed.ends`
2. `parsed.ends.last` returns `nil` instead of a `[name, line_number]`
tuple
3. The generator attempts to call `line_number_after + 1` where
`line_number_after` is `nil`
4. This results in a `NoMethodError: undefined method '+' for nil`

**Error Stack Trace:**
```
undefined method '+' for nil (NoMethodError)
line_number_after + 1
```

## Root Cause

The issue occurs in two methods within `AnnotatedFile::Generator`:

1. **`content_annotated_after`** - Tries to access `line_number_after +
1` without checking for `nil`
2. **`determine_annotation_position`** - Returns `nil` when
`parsed.starts` is empty

## Solution

### Core Fixes

**1. Enhanced `content_annotated_after` method:**
- Added explicit `nil` check for `line_number_after`
- Provides graceful fallback behavior for empty files
- Appends annotations to the end of file content when no classes/modules
are found

**2. Enhanced `determine_annotation_position` method:**
- Added safety check for empty `parsed.starts` array
- Returns safe default `[nil, 0]` tuple for empty files
- Maintains backward compatibility with existing logic

## Edge Cases Handled

1. **Completely empty files** (`""`) - Annotations added as file content
2. **Whitespace-only files** - Annotations placed appropriately
3. **Comment-only files** - Annotations placed before/after comments
based on position
4. **Files with no classes/modules** - Safe fallback behavior

## Related Issues

Fixes #182

## Testing Instructions

1. Create an empty model file: `touch app/models/empty_model.rb`
2. Run: `annotaterb models --force`
3. Verify: No error occurs and annotation is added to the file
4. Test with files containing only comments
5. Run existing test suite: `bundle exec rspec`

Co-authored-by: Andrew W. Lee <[email protected]>

Author: tanukiti1987

lib/annotate_rb/model_annotator/annotated_file/generator.rb

@@ -63,6 +63,9 @@ def content_annotated_before(parsed, content_without_annotations, write_position
         # When nested_position is enabled, finds the most deeply nested class declaration
         # to place annotations directly above nested classes instead of at the file top.
         def determine_annotation_position(parsed)
+          # Handle empty files where no classes/modules are found
+          return [nil, 0] if parsed.starts.empty?
+
           return parsed.starts.first unless @options[:nested_position]
 
           class_entries = parsed.starts.select { |name, _line| parsed.type_map[name] == :class }
@@ -90,6 +93,17 @@ def determine_indentation(content_without_annotations, line_number_before)
         def content_annotated_after(parsed, content_without_annotations)
           _constant_name, line_number_after = parsed.ends.last
 
+          # Handle empty files where no classes/modules are found
+          if line_number_after.nil?
+            content_lines = content_without_annotations.lines
+            # For empty files, append annotations at the end
+            content_with_annotations_written_after = []
+            content_with_annotations_written_after << content_lines
+            content_with_annotations_written_after << $/ unless content_lines.empty?
+            content_with_annotations_written_after << @new_wrapped_annotations.lines
+            return content_with_annotations_written_after.join
+          end
+
           content_with_annotations_written_after = []
           content_with_annotations_written_after << content_without_annotations.lines[0..line_number_after]
           content_with_annotations_written_after << $/

spec/lib/annotate_rb/model_annotator/annotated_file/generator_spec.rb

@@ -738,5 +738,160 @@ module AnotherModule
         end
       end
     end
+
+    context "when file is empty" do
+      let(:file_content) { "" }
+      let(:new_annotations) do
+        <<~ANNOTATIONS
+          # == Schema Information
+          #
+          # Table name: users
+          #
+          #  id                     :bigint           not null, primary key
+          #
+        ANNOTATIONS
+      end
+
+      context 'with position "before"' do
+        let(:options) { AnnotateRb::Options.new({position_in_class: "before"}) }
+
+        let(:expected_content) do
+          <<~CONTENT
+            # == Schema Information
+            #
+            # Table name: users
+            #
+            #  id                     :bigint           not null, primary key
+            #
+          CONTENT
+        end
+
+        it "adds annotations to empty file" do
+          is_expected.to eq(expected_content)
+        end
+      end
+
+      context 'with position "after"' do
+        let(:options) { AnnotateRb::Options.new({position_in_class: "after"}) }
+
+        let(:expected_content) do
+          <<~CONTENT
+            # == Schema Information
+            #
+            # Table name: users
+            #
+            #  id                     :bigint           not null, primary key
+            #
+          CONTENT
+        end
+
+        it "adds annotations to empty file" do
+          is_expected.to eq(expected_content)
+        end
+      end
+
+      context 'with position "top"' do
+        let(:options) { AnnotateRb::Options.new({position_in_class: "top"}) }
+
+        let(:expected_content) do
+          <<~CONTENT
+            # == Schema Information
+            #
+            # Table name: users
+            #
+            #  id                     :bigint           not null, primary key
+            #
+          CONTENT
+        end
+
+        it "adds annotations to empty file" do
+          is_expected.to eq(expected_content)
+        end
+      end
+
+      context 'with position "bottom"' do
+        let(:options) { AnnotateRb::Options.new({position_in_class: "bottom"}) }
+
+        let(:expected_content) do
+          <<~CONTENT
+            # == Schema Information
+            #
+            # Table name: users
+            #
+            #  id                     :bigint           not null, primary key
+            #
+          CONTENT
+        end
+
+        it "adds annotations to empty file" do
+          is_expected.to eq(expected_content)
+        end
+      end
+    end
+
+    context "when file contains only whitespace and comments" do
+      let(:file_content) do
+        <<~FILE
+          # Some random comment
+          
+          # Another comment
+        FILE
+      end
+      let(:new_annotations) do
+        <<~ANNOTATIONS
+          # == Schema Information
+          #
+          # Table name: users
+          #
+          #  id                     :bigint           not null, primary key
+          #
+        ANNOTATIONS
+      end
+
+      context 'with position "before"' do
+        let(:options) { AnnotateRb::Options.new({position_in_class: "before"}) }
+
+        let(:expected_content) do
+          <<~CONTENT
+            # == Schema Information
+            #
+            # Table name: users
+            #
+            #  id                     :bigint           not null, primary key
+            #
+            # Some random comment
+            
+            # Another comment
+          CONTENT
+        end
+
+        it "adds annotations at the beginning of file with only comments" do
+          is_expected.to eq(expected_content)
+        end
+      end
+
+      context 'with position "after"' do
+        let(:options) { AnnotateRb::Options.new({position_in_class: "after"}) }
+
+        let(:expected_content) do
+          <<~CONTENT
+            # Some random comment
+            
+            # Another comment
+
+            # == Schema Information
+            #
+            # Table name: users
+            #
+            #  id                     :bigint           not null, primary key
+            #
+          CONTENT
+        end
+
+        it "adds annotations at the end of file with only comments" do
+          is_expected.to eq(expected_content)
+        end
+      end
+    end
   end
 end

spec/lib/annotate_rb/model_annotator/file_parser/custom_parser_spec.rb

@@ -321,5 +321,82 @@ class User < ApplicationRecord
         check_it_parses_correctly
       end
     end
+
+    context "when file is completely empty" do
+      let(:input) { "" }
+      let(:expected_comments) { [] }
+      let(:expected_starts) { [] }
+      let(:expected_ends) { [] }
+
+      it "parses correctly and returns empty arrays" do
+        check_it_parses_correctly
+      end
+    end
+
+    context "when file contains only whitespace" do
+      let(:input) do
+        <<~FILE
+          
+          
+          
+        FILE
+      end
+      let(:expected_comments) { [] }
+      let(:expected_starts) { [] }
+      let(:expected_ends) { [] }
+
+      it "parses correctly and returns empty arrays" do
+        check_it_parses_correctly
+      end
+    end
+
+    context "when file contains only comments" do
+      let(:input) do
+        <<~FILE
+          # This is just a comment
+          # Another comment
+          
+          # Final comment
+        FILE
+      end
+      let(:expected_comments) do
+        [
+          ["# This is just a comment", 0],
+          ["# Another comment", 1],
+          ["# Final comment", 3]
+        ]
+      end
+      let(:expected_starts) { [] }
+      let(:expected_ends) { [] }
+
+      it "parses comments but returns empty arrays for starts and ends" do
+        check_it_parses_correctly
+      end
+    end
+
+    context "when file contains only block comments" do
+      let(:input) do
+        <<~FILE
+          =begin
+          This is a multi-line comment
+          with no actual Ruby code
+          =end
+        FILE
+      end
+      let(:expected_comments) do
+        [
+          ["=begin", 0],
+          ["This is a multi-line comment", 1],
+          ["with no actual Ruby code", 2],
+          ["=end", 3]
+        ]
+      end
+      let(:expected_starts) { [] }
+      let(:expected_ends) { [] }
+
+      it "parses block comments but returns empty arrays for starts and ends" do
+        check_it_parses_correctly
+      end
+    end
   end
 end