no_comments 0.1.5 → 0.1.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '0778f4eb4bbe1723231e1668730a87d462f154221fb7097fa35d21d5b34e832c'
-  data.tar.gz: f65eec62db3eab6acec0f44f4b02a2bc5983bf559aae3cec96855c4996d66a5e
+  metadata.gz: b0866e1f078f1e7465e0196ca4a71cac6956bb607452f7fec15f55ebf7e2f417
+  data.tar.gz: fbec43970d78b83199c3c5288e72fb300bb4382c82c98555c4e7089c4abddf88
 SHA512:
-  metadata.gz: 4d8805b6f04b9a1ac48c8992b274f29c5f5ca0574ebebe2ed28fa9b2abf92e2bc87063100ade5365b73fd8d0b185142b521683e3b84a48c863897a7d656c7b27
-  data.tar.gz: 9c1af8324d295c9bc1fc1174d4789004e001758ac3e198d8c1735c27ef64e317367158b0097301331a4bb591810567f4c8e33687b45dc6a956c52e99fff2d706
+  metadata.gz: 32de2f75bcaf62648b319e6bab3da0020115ce52454c63081f91e71a6670a0fa6c5f66e0da0043a1bd22fc68a547a2622c19ddb55feb95046ff06843b34c175e
+  data.tar.gz: 292f77329f185d695359a9d14e0b724118409a2bb44904488d761e7ff89eeaf9ef6f6286630fb6f0ff40f2b8d63089420c774d29a8b575585b72daa197994658

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,15 @@
+# frozen_string_literal: true
+
+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,12 @@
 # frozen_string_literal: true
 
 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,15 +14,16 @@ 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)
       end
-
       cleaned_content = @result_lines.join("\n")
       cleaned_content += "\n" unless cleaned_content.empty?
       [cleaned_content, @comments]
@@ -30,7 +34,24 @@ 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)
+        @result_lines << line.rstrip
+      elsif stripped_line.start_with?("#")
+        if tool_comment?(stripped_line)
+          @result_lines << line.rstrip
+        else
+          @comments << [@line_number, stripped_line]
+        end
       else
+        @code_started = true
         handle_regular_line(line, stripped_line)
       end
     end
@@ -42,7 +63,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 +71,10 @@ 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)
+        @result_lines << line.rstrip
       else
         process_code_line(line)
       end
@@ -69,89 +92,15 @@ 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)
+        @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,84 @@
+# frozen_string_literal: true
+
+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?
+      return true if line[idx - 1..idx] == "::"
+
+      prev_char = line[idx]
+      operator_chars = %w[\[ = + - * / % | & ! < > ^ ~ ( , ? : ; {]
+      operator_chars.include?(prev_char)
+    end
+  end
+end

data/lib/no_comments/remover.rb

@@ -2,7 +2,6 @@
 
 require "no_comments/version"
 require "no_comments/content_processor"
-
 module NoComments
   class Remover
     def self.clean(file_path, audit: false)
@@ -18,9 +17,8 @@ module NoComments
     def self.process_file(file_path, audit: false)
       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)
       else
@@ -32,11 +30,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.7"
 end

data/lib/no_comments.rb

@@ -2,6 +2,5 @@
 
 require "no_comments/content_processor"
 require "no_comments/remover"
-
 module NoComments
 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.7
 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,11 +25,13 @@ 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
-homepage:
+homepage: https://github.com/justi/no_comments
 licenses:
 - MIT
 metadata:
@@ -52,5 +54,6 @@ requirements: []
 rubygems_version: 3.4.19
 signing_key:
 specification_version: 4
-summary: Remove comments from Ruby files
+summary: NoComments is a Ruby gem designed to clean up .rb files by removing unnecessary
+  comments, leaving your code clean and ready for deployment.
 test_files: []