no_comments 0.1.5 → 0.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0778f4eb4bbe1723231e1668730a87d462f154221fb7097fa35d21d5b34e832c'
-  data.tar.gz: f65eec62db3eab6acec0f44f4b02a2bc5983bf559aae3cec96855c4996d66a5e
+  metadata.gz: 71ade70ce6b697e2f4f4244766a9b7914c04b628eb9c87ba4f4273b8c4cbb846
+  data.tar.gz: 9ed3453c9e8c9fe097e6b5506ada7917adcd54e10ec7bfd0e2297508612eff12
 SHA512:
-  metadata.gz: 4d8805b6f04b9a1ac48c8992b274f29c5f5ca0574ebebe2ed28fa9b2abf92e2bc87063100ade5365b73fd8d0b185142b521683e3b84a48c863897a7d656c7b27
-  data.tar.gz: 9c1af8324d295c9bc1fc1174d4789004e001758ac3e198d8c1735c27ef64e317367158b0097301331a4bb591810567f4c8e33687b45dc6a956c52e99fff2d706
+  metadata.gz: 6768a1bafedf5cf9abb143c5a08cca1bd534122d888fde625ebb124fb1591b6f6fce9c8585463ab2f27692a322c85c1f119d454b4f4847c03428545174a8b0a9
+  data.tar.gz: c3f05e89997be0923516daf3599a080b222d19c1cbca23e5b52553e282fcdfe7246e7cbbc1e2b4fa543181765b23dc36f35ee307337c2d29fd9ca39b72e3a55f

data/.rubocop.yml

@@ -17,8 +17,10 @@ Metrics/BlockLength:
     - 'spec/no_comments/**/*'
 
 Metrics/ClassLength:
-  Max: 120
+  Max: 150
 
+Metrics/MethodLength:
+    Max: 20
 
 Style/Documentation:
   Enabled: false

data/README.md

@@ -1,23 +1,52 @@
-# no_comments
+# NoComments
+NoComments is a Ruby gem designed to clean up `.rb` files by removing unnecessary comments, leaving your code clean and ready for deployment.
 
-`no_comments` is a simple Ruby gem that removes comments from `.rb` files. It can handle single-line, block and inline comments, leaving your code clean and readable.
+## What This Gem Does
+It removes:
 
----
+- Single-line comments (e.g., # This is a comment)
+- Block comments (e.g., =begin ... =end)
+- Inline comments (e.g., puts 'Hello' # This is a comment)
+
+It preserves:
+
+- Shebangs (e.g., #!/usr/bin/env ruby)
+- Magic comments (e.g., # frozen_string_literal: true)
+- Tool-defined comments (e.g., # rubocop:disable all)
 
 ## Table of Contents
+1. [When to Use This Gem](#When-to-Use-This-Gem)
+2. [When Not to Use This Gem](#When-Not-to-Use-This-Gem)
+3. [Installation](#Installation)
+4. [Usage](#Usage)
+   - [Audit Mode](#Audit-Mode)
+   - [CLI](#CLI)
+5. [Testing](#Testing)
+6. [Contributing](#Contributing)
+7. [License](#License)
+8. [TODO](#TODO)
 
-1. [Installation](#installation)
-2. [Usage](#usage)
-3. [Testing](#testing)
-4. [Contribution](#contribution)
-5. [License](#license)
-6. [TODO](#todo)
+## When to Use This Gem
 
----
+NoComments is particularly useful in the following scenarios:
+
+- **Auto-Generated or Boilerplate Code:** Helps clean up scaffolding or boilerplate comments, commonly generated in frameworks like Rails.
+- **Codebases with Overused Comments:** Removes redundant comments that restate obvious code.
+- **Continuous Integration/Code Review Workflows:** Automates comment cleanup during CI/CD processes.
+- **Educational Projects:** Streamlines code by removing teaching-related comments after the learning phase.
+- **Maintaining Open Source Projects:** Ensures consistency by removing unnecessary comments in contributions.
+
+## When Not to Use This Gem
+
+While the gem is powerful, it may not be suitable in these scenarios:
+
+- **Code with Valuable Documentation Comments:** Avoid using the gem if your code relies on comments for explaining complex logic or business rules.
+- **Codebases Requiring Compliance:** In regulated industries, where specific comments are required for audits or documentation purposes.
+- **Highly Dynamic Environments:** In fast-changing projects, comments might provide crucial context for recent changes or decisions.
 
 ## Installation
 
-To install `no_comments`, add it to your Gemfile:
+To install no_comments, add it to your Gemfile:
 
 ```ruby
 gem 'no_comments'
@@ -27,94 +56,109 @@ Then execute:
 ```bash
 bundle install
 ```
-Or install it yourself using the following command:
+
+Or install directly:
 
 ```bash
 gem install no_comments
 ```
 
-
 ## Usage
-To clean up comments from a .rb file or directory, use the `NoComments::Remover.clean` method. This will remove all single-line, block and inline comments from the file or directory.
+
+### Cleaning Files or Directories
+To clean up comments from a `.rb` file or an entire directory, use the `NoComments::Remover.clean` method:
 
 ```ruby
 require 'no_comments'
 
+# Clean a single file
 NoComments::Remover.clean('path/to/your_file.rb')
-NoComments::Remover.clean('path/to/your_directory')
 
+# Clean all `.rb` files in a directory
+NoComments::Remover.clean('path/to/your_directory')
 ```
 ### Audit Mode
-
-To use the audit mode, pass the `audit: true` flag to the `clean` method. This will output the file paths and lines containing comments without modifying the files.
-
-#### Example
+Audit mode allows you to preview the comments that would be removed without modifying the files. Use the `audit: true` flag with the `clean` method:
 
 ```ruby
 NoComments::Remover.clean('example.rb', audit: true)
 ```
-#### Output
-
+#### Example Output:
+`example.rb`:
+```ruby
+# This is a comment
+def hello
+  puts 'Hello' # Another comment
+end
+```
+Output:
 ```bash
 File: example.rb
   Line 1: # This is a comment
   Line 3: # Another comment
 ```
 
-### Command-Line Interface (CLI)
-
-You can use `no_comments` directly from the command line to clean or audit `.rb` files.
-
-#### Clean Comments
-
-To remove comments from a file, use:
+### CLI
+`NoComments` provides a Command Line Interface (CLI) for easy comment cleanup. The CLI supports the following options:
 
+#### Clean Comments:
 ```bash
 no_comments -p path/to/file.rb
 no_comments -p path/to/directory
 ```
-#### Audit mode
-
-To run `no_comments` in audit mode without modifying files, use the `--audit` flag:
-
+#### Audit Mode:
 ```bash
 no_comments -p path/to/file.rb --audit
 no_comments -p path/to/directory --audit
 ```
 
 ## Testing
-`no_comments` uses RSpec for testing. To run the tests, first make sure all dependencies are installed:
 
+This gem uses RSpec for testing. To run tests:
+
+1. Install dependencies:
 ```bash
 bundle install
 ```
-Then, run the tests with:
-
+2. Run the test suite::
 ```bash
 bundle exec rspec
 ```
-All tests are located in the spec directory and cover the main functionality of the gem, ensuring it properly removes comments from Ruby files.
 
-## Contribution
+Tests are located in the spec directory and ensure that the gem behaves as expected, removing comments appropriately while preserving essential ones.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/justi/no_comments.
+## Contributing
+We welcome contributions! To contribute:
 
-To contribute:
-
-Fork the repository.
-Create a new branch (git checkout -b feature-branch).
-Make your changes.
-Commit your changes (git commit -m 'Add new feature').
-Push to the branch (git push origin feature-branch).
-Open a pull request.
+1. Fork the repository.
+2. Create a new branch for your feature or fix:
+```bash
+git checkout -b feature-branch
+```
+3. Make your changes.
+4. Commit your changes with a descriptive message:
+```bash
+git commit -m 'Add new feature'
+```
+5. Push your branch:
+```bash
+git push origin feature-branch
+```
+6. Open a pull request on GitHub.
 
-Please ensure that your code follows the existing style and that all tests pass.
+Please ensure your code follows the existing style and that all tests pass before submitting.
 
 ## License
-The gem is available as open source under the terms of the MIT License.
-
+This gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
 
 ## TODO
-- Add support to magic comments (e.g. `# frozen_string_literal: true`) https://docs.ruby-lang.org/en/3.2/syntax/comments_rdoc.html - thanks [Chris](https://github.com/khasinski)!
-- Option to keep documentation comments (e.g. `# @param`) https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Style/Documentation
-- Option to clean all files in a directory except for a specified file
+Planned features for future updates:
+- **Option to Keep Documentation Comments:**
+  - Preserve comments like # @param or # @return for tools like YARD.
+  Reference: [RuboCop documentation cop](https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Style/Documentation).
+- **Selective Cleaning:**
+  - Allow users to clean all files in a directory except for specified ones.
+
+---
+## Why Use NoComments?
+NoComments is the perfect tool for keeping your codebase clean and focused, whether you're starting fresh or maintaining an existing project. By automating comment cleanup, you can focus on what matters: writing great code.

data/lib/no_comments/comment_detector.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+# lib/no_comments/comment_detector.rb
+
+module NoComments
+  module CommentDetector
+    MAGIC_COMMENT_REGEX = /\A#.*\b(?:frozen_string_literal|encoding|coding|warn_indent|fileencoding)\b.*\z/
+    TOOL_COMMENT_REGEX = /\A#\s*(?:rubocop|reek|simplecov|coveralls|pry|byebug|noinspection|sorbet|type)\b/
+
+    def magic_comment?(stripped_line)
+      stripped_line.match?(MAGIC_COMMENT_REGEX)
+    end
+
+    def tool_comment?(stripped_line)
+      stripped_line.match?(TOOL_COMMENT_REGEX)
+    end
+  end
+end

data/lib/no_comments/content_processor.rb

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
+# lib/no_comments/content_processor.rb
+
 require "no_comments/version"
+require "no_comments/comment_detector"
+require "no_comments/line_parser"
 
 module NoComments
   class ContentProcessor
+    include CommentDetector
+    include LineParser
+
     def initialize
       @comments = []
       @result_lines = []
@@ -11,10 +18,13 @@ module NoComments
       @in_heredoc = false
       @heredoc_delimiter = nil
       @line_number = 0
+      @code_started = false
     end
 
     def process(content)
-      content.each_line do |line|
+      lines = content.lines
+
+      lines.each do |line|
         @line_number += 1
         stripped_line = line.strip
         process_line(line, stripped_line)
@@ -30,11 +40,32 @@ module NoComments
         handle_multiline_comment(stripped_line)
       elsif @in_heredoc
         handle_heredoc(line, stripped_line)
+      elsif !@code_started
+        handle_initial_lines(line, stripped_line)
       else
         handle_regular_line(line, stripped_line)
       end
     end
 
+    def handle_initial_lines(line, stripped_line)
+      if stripped_line.empty? || stripped_line.start_with?("#!") || magic_comment?(stripped_line)
+        # Preserve blank lines, shebang lines, and magic comments
+        @result_lines << line.rstrip
+      elsif stripped_line.start_with?("#")
+        if tool_comment?(stripped_line)
+          # Preserve tool-specific comments
+          @result_lines << line.rstrip
+        else
+          # Regular comment at the top, remove it
+          @comments << [@line_number, stripped_line]
+        end
+      else
+        # First code line encountered
+        @code_started = true
+        handle_regular_line(line, stripped_line)
+      end
+    end
+
     def handle_multiline_comment(stripped_line)
       @comments << [@line_number, stripped_line]
       @in_multiline_comment = false if stripped_line == "=end"
@@ -42,7 +73,7 @@ module NoComments
 
     def handle_heredoc(line, stripped_line)
       @result_lines << line.rstrip
-      @in_heredoc, @heredoc_delimiter = self.class.update_heredoc_state(
+      @in_heredoc, @heredoc_delimiter = update_heredoc_state(
         stripped_line, @heredoc_delimiter
       )
     end
@@ -50,8 +81,11 @@ module NoComments
     def handle_regular_line(line, stripped_line)
       if stripped_line == "=begin"
         start_multiline_comment(stripped_line)
-      elsif (heredoc_start = self.class.detect_heredoc_start(line))
+      elsif (heredoc_start = detect_heredoc_start(line))
         start_heredoc(line, heredoc_start)
+      elsif stripped_line.start_with?("#") && tool_comment?(stripped_line)
+        # Preserve tool-specific comments anywhere in the code
+        @result_lines << line.rstrip
       else
         process_code_line(line)
       end
@@ -69,89 +103,16 @@ module NoComments
     end
 
     def process_code_line(line)
-      code_part, comment_part = self.class.split_line(line)
-      @comments << [@line_number, comment_part.strip] if comment_part
-      return if code_part.strip.empty?
-
-      @result_lines << code_part.rstrip
-    end
-
-    # rubocop:disable Metrics/AbcSize
-    # rubocop:disable Metrics/MethodLength
-    # rubocop:disable Metrics/PerceivedComplexity
-    # rubocop:disable Metrics/CyclomaticComplexity
-    # rubocop:disable Metrics/BlockNesting
-    def self.split_line(line)
-      in_single_quote = false
-      in_double_quote = false
-      in_regex = false
-      escape = false
-      index = 0
-
-      while index < line.length
-        char = line[index]
-
-        if escape
-          escape = false
-        else
-          case char
-          when "\\"
-            escape = true
-          when "'"
-            in_single_quote = !in_single_quote unless in_double_quote || in_regex
-          when '"'
-            in_double_quote = !in_double_quote unless in_single_quote || in_regex
-          when "/"
-            if in_regex
-              in_regex = false
-            elsif !in_single_quote && !in_double_quote &&
-                  preceding_char_is_operator?(line, index)
-              in_regex = true
-            end
-          when "#"
-            result = handle_comment_character(line, index, in_single_quote, in_double_quote, in_regex)
-            return result if result
-          end
-        end
-        index += 1
-      end
-      [line, nil]
-    end
-
-    # rubocop:enable Metrics/AbcSize
-    # rubocop:enable Metrics/MethodLength
-    # rubocop:enable Metrics/PerceivedComplexity
-    # rubocop:enable Metrics/CyclomaticComplexity
-    # rubocop:enable Metrics/BlockNesting
-
-    def self.handle_comment_character(line, index, in_single_quote, in_double_quote, in_regex)
-      unless in_single_quote || in_double_quote || in_regex
-        code_part = line[0...index]
-        comment_part = line[index..]
-        return [code_part, comment_part]
-      end
-      nil
-    end
-
-    def self.update_heredoc_state(stripped_line, heredoc_delimiter)
-      if stripped_line == heredoc_delimiter
-        [false, nil]
+      code_part, comment_part = split_line(line)
+      if comment_part && tool_comment?(comment_part.strip)
+        # Preserve tool-specific inline comments
+        @result_lines << ("#{code_part.rstrip} #{comment_part.strip}")
       else
-        [true, heredoc_delimiter]
-      end
-    end
+        @comments << [@line_number, comment_part.strip] if comment_part
+        return if code_part.strip.empty?
 
-    def self.detect_heredoc_start(line)
-      if (match = line.match(/<<[-~]?(["'`]?)(\w+)\1/))
-        match[2]
+        @result_lines << code_part.rstrip
       end
     end
-
-    def self.preceding_char_is_operator?(line, index)
-      return true if index.zero?
-
-      prev_char = line[index - 1]
-      prev_char =~ %r{[\s(,=+\-*/%|&!<>?:]}
-    end
   end
 end

data/lib/no_comments/line_parser.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+# lib/no_comments/line_parser.rb
+
+module NoComments
+  module LineParser
+    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable Metrics/AbcSize
+    # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
+    # rubocop:disable Metrics/BlockNesting
+    #
+    def split_line(line)
+      in_single_quote = false
+      in_double_quote = false
+      in_regex = false
+      escape = false
+      index = 0
+
+      while index < line.length
+        char = line[index]
+
+        if escape
+          escape = false
+        else
+          case char
+          when "\\"
+            escape = true
+          when "'"
+            in_single_quote = !in_single_quote unless in_double_quote || in_regex
+          when '"'
+            in_double_quote = !in_double_quote unless in_single_quote || in_regex
+          when "/"
+            if in_regex
+              in_regex = false
+            elsif !in_single_quote && !in_double_quote &&
+                  preceding_char_is_operator?(line, index)
+              in_regex = true
+            end
+          when "#"
+            result = handle_comment_character(line, index, in_single_quote, in_double_quote, in_regex)
+            return result if result
+          end
+        end
+        index += 1
+      end
+      [line, nil]
+    end
+    # rubocop:enable Metrics/MethodLength
+    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/CyclomaticComplexity
+    # rubocop:enable Metrics/PerceivedComplexity
+    # rubocop:enable Metrics/BlockNesting
+
+    def handle_comment_character(line, index, in_single_quote, in_double_quote, in_regex)
+      unless in_single_quote || in_double_quote || in_regex
+        code_part = line[0...index]
+        comment_part = line[index..]
+        return [code_part, comment_part]
+      end
+      nil
+    end
+
+    def update_heredoc_state(stripped_line, heredoc_delimiter)
+      if stripped_line == heredoc_delimiter
+        [false, nil]
+      else
+        [true, heredoc_delimiter]
+      end
+    end
+
+    def detect_heredoc_start(line)
+      if (match = line.match(/<<[-~]?(["'`]?)(\w+)\1/))
+        match[2]
+      end
+    end
+
+    def preceding_char_is_operator?(line, index)
+      idx = index - 1
+      idx -= 1 while idx >= 0 && line[idx] =~ /\s/
+
+      return true if idx.negative? # Beginning of line or after whitespace
+
+      # Handle special case where preceding character is part of a multi-character operator
+      return true if line[idx - 1..idx] == "::"
+
+      prev_char = line[idx]
+
+      # List of operator characters
+      operator_chars = %w[\[ = + - * / % | & ! < > ^ ~ ( , ? : ; {]
+
+      # Return true if preceding character is an operator
+      operator_chars.include?(prev_char)
+    end
+  end
+end

data/lib/no_comments/remover.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# lib/no_comments/remover.rb
+
 require "no_comments/version"
 require "no_comments/content_processor"
 
@@ -19,7 +21,8 @@ module NoComments
       validate_file_extension(file_path)
       content = File.read(file_path)
 
-      cleaned_content, comments = process_content(content)
+      processor = ContentProcessor.new
+      cleaned_content, comments = processor.process(content)
 
       if audit
         print_audit(file_path, comments)
@@ -32,11 +35,6 @@ module NoComments
       raise "Only Ruby files are supported" unless file_path.end_with?(".rb")
     end
 
-    def self.process_content(content)
-      processor = NoComments::ContentProcessor.new
-      processor.process(content)
-    end
-
     def self.print_audit(file_path, comments)
       return if comments.empty?
 

data/lib/no_comments/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module NoComments
-  VERSION = "0.1.5"
+  VERSION = "0.1.6"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: no_comments
 version: !ruby/object:Gem::Version
-  version: 0.1.5
+  version: 0.1.6
 platform: ruby
 authors:
 - Justyna
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-11-16 00:00:00.000000000 Z
+date: 2024-11-17 00:00:00.000000000 Z
 dependencies: []
 description:
 email:
@@ -25,7 +25,9 @@ files:
 - Rakefile
 - exe/no_comments
 - lib/no_comments.rb
+- lib/no_comments/comment_detector.rb
 - lib/no_comments/content_processor.rb
+- lib/no_comments/line_parser.rb
 - lib/no_comments/remover.rb
 - lib/no_comments/version.rb
 - sig/no_comments.rbs