file_annotate 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4a0082d2dceab828995d5ceaf298423e28d57eedf5670049e394bd6edf40f3dd
+  data.tar.gz: 6a2a3e956cc4652add4225080c4d4b15628de0ec3e5076f307748f92787d151a
+SHA512:
+  metadata.gz: f6c851f1c078abe2143b7424b3b62ca929c6db8ec3d827644f11c513352e7732c4bc1635c575c62ea4fba613ef4f9e11e87f9ad9b7c1fbe4897184848138566c
+  data.tar.gz: fbb2662517dcaf9ca36725a1a61dd0d949bdd6d6f575b6b41b593f65ee20db4d7c6a6572c20b88540178b035bb8f1e1071b3e81ef301cbd86e5a98b3512826d8

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,22 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Style/AsciiComments:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+require:
+  - ./lib/rubocop/cop/file_annotate/first_line_comment.rb
+
+FileAnnotate/FirstLineComment:
+  Enabled: true
+  EnforcedStyle: forbidden # default is 'required', can be 'forbidden'

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2025-03-03
+
+- Initial release

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 jedivulyliu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,63 @@
+# FileAnnotate 檔案路徑註解套件
+
+FileAnnotate 是一個 Ruby Gem，提供兩大功能：
+
+CLI 批次處理：自動在專案內每個 .rb 檔案的第一行插入該檔案路徑的註解。
+
+RuboCop 插件：提供自訂 Cop，檢查並確保 .rb 檔案第一行為正確的檔案路徑註解，並支援自動修正。
+
+## Installation 安裝方式
+
+在專案的 Gemfile 中加入：
+```ruby
+gem "file_annotate"
+```
+然後執行：
+```bash
+bundle install
+```
+或是直接安裝：
+```bash
+gem install file_annotate
+```
+
+## Usage 使用說明
+
+✅ CLI 批次處理
+執行以下指令，會自動為專案中所有 .rb 檔案加上第一行檔案路徑註解：
+```bash
+file_annotate add
+```
+
+執行以下指令，會自動檢查專案中所有 .rb 檔案的第一行或第二行為檔案路徑註解時，給予刪除：
+```bash
+file_annotate remove
+```
+
+✅ RuboCop 規則檢查
+在你的專案 .rubocop.yml 檔案中加入：
+```yaml
+require:
+  - file_annotate/rubocop
+
+FileAnnotate/FirstLineComment:
+  Enabled: true
+```
+
+然後執行 RuboCop：
+```bash
+rubocop
+```
+
+若需要自動修正缺少的檔案註解，請使用：
+```bash
+rubocop -A
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/file_annotate.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/bin/file_annotate

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# bin/file_annotate
+
+require "file_annotate"
+
+FileAnnotate::CLI.start

data/lib/file_annotate/annotator.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module FileAnnotate
+  # 負責對檔案內容進行註解的處理
+  class Annotator
+    def self.annotate_all
+      each_rb_file do |file|
+        lines = File.readlines(file)
+        next if annotated?(lines, file)
+
+        insert_annotation!(lines, file)
+        File.write(file, lines.join)
+      end
+    end
+
+    def self.remove_all
+      each_rb_file do |file|
+        lines = File.readlines(file)
+        File.write(file, lines.join) if remove_annotation!(lines, file)
+      end
+    end
+
+    def self.each_rb_file(&block)
+      Dir.glob("**/*.rb").each(&block)
+    end
+
+    def self.annotation_text(file)
+      "# #{file}"
+    end
+
+    def self.annotated?(lines, file)
+      lines.first&.strip == annotation_text(file)
+    end
+
+    def self.insert_annotation!(lines, file)
+      lines.unshift("#{annotation_text(file)}\n")
+    end
+
+    def self.remove_annotation!(lines, file)
+      if annotated?(lines, file)
+        lines.delete_at(0)
+        true
+      else
+        false
+      end
+    end
+  end
+end

data/lib/file_annotate/cli.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "thor"
+require "file_annotate/annotator"
+
+module FileAnnotate
+  # CLI 負責處理指令列操作
+  class CLI < Thor
+    desc "add", "批次將檔案路徑註解插入所有 .rb 檔案"
+    def add
+      puts "=== FileAnnotate CLI - Add file path comments ==="
+      FileAnnotate::Annotator.annotate_all
+      puts "Done!"
+    end
+
+    desc "remove", "批次移除所有檔案的檔案路徑註解"
+    def remove
+      puts "=== FileAnnotate CLI - Remove file path comments ==="
+      FileAnnotate::Annotator.remove_all
+      puts "Done!"
+    end
+  end
+end

data/lib/file_annotate/rubocop.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "../rubocop/cop/file_annotate/first_line_comment"

data/lib/file_annotate/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module FileAnnotate
+  VERSION = "0.1.0"
+end

data/lib/file_annotate.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "file_annotate/version"
+require_relative "file_annotate/cli"
+require_relative "file_annotate/annotator"
+require "rubocop"
+require_relative "rubocop/cop/file_annotate/first_line_comment"
+
+module FileAnnotate
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/lib/rubocop/cop/file_annotate/first_line_comment.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require 'pathname'
+
+module RuboCop
+  module Cop
+    module FileAnnotate
+      # 檢查檔案開頭的相對路徑註解是否符合設定
+      class FirstLineComment < Base
+        extend AutoCorrector
+
+        MSG_MISSING = "Missing file path comment."
+        MSG_FORBIDDEN = "File path comment is forbidden on the first line."
+
+        def on_new_investigation
+          return if processed_source.lines.empty?
+
+          @project_root = Pathname.pwd
+          @absolute_path = Pathname.new(processed_source.file_path)
+          @relative_path = @absolute_path.relative_path_from(@project_root).to_s
+          @expected_comment = "# #{@relative_path}"
+
+          case enforced_style
+          when :required
+            check_required
+          when :forbidden
+            check_forbidden
+          end
+        end
+
+        private
+
+        def enforced_style
+          cop_config.fetch('EnforcedStyle', 'required').to_sym
+        end
+
+        def check_required
+          return if annotated_correctly?
+
+          position = 0 # 檔案開頭位置
+          range = Parser::Source::Range.new(processed_source.buffer, position, position)
+
+          add_offense(range, message: MSG_MISSING) do |corrector|
+            corrector.insert_before(range, "#{@expected_comment}\n")
+          end
+        end
+
+        def check_forbidden
+          first_line = processed_source.lines[0]&.strip
+          return unless first_line == @expected_comment
+
+          range = processed_source.buffer.line_range(1)
+          add_offense(range, message: MSG_FORBIDDEN) do |corrector|
+            corrector.remove(range_with_trailing_newline(range))
+          end
+        end
+
+        def annotated_correctly?
+          first_line = processed_source.lines[0]&.strip
+          first_line == @expected_comment
+        end
+
+        def range_with_trailing_newline(range)
+          buffer = processed_source.buffer
+          source = buffer.source
+          end_pos = range.end_pos
+          end_pos += 1 if source[end_pos] == "\n"
+          Parser::Source::Range.new(buffer, range.begin_pos, end_pos)
+        end
+      end
+    end
+  end
+end

data/sig/file_annotate.rbs

@@ -0,0 +1,4 @@
+module FileAnnotate
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,105 @@
+--- !ruby/object:Gem::Specification
+name: file_annotate
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- jedivulyliu
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2025-03-05 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+- !ruby/object:Gem::Dependency
+  name: thor
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.60'
+description: 批次掃描 .rb 檔案並加入路徑註解，並支援 RuboCop 檢查
+email:
+- jedivuly@gmail.com
+executables:
+- file_annotate
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/file_annotate
+- lib/file_annotate.rb
+- lib/file_annotate/annotator.rb
+- lib/file_annotate/cli.rb
+- lib/file_annotate/rubocop.rb
+- lib/file_annotate/version.rb
+- lib/rubocop/cop/file_annotate/first_line_comment.rb
+- sig/file_annotate.rbs
+homepage: https://github.com/jedivuly/file_annotate
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/jedivuly/file_annotate
+  source_code_uri: https://github.com/jedivuly/file_annotate
+  changelog_uri: https://github.com/jedivuly/file_annotate/blob/main/CHANGELOG.md
+  rubocop_extension: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.33
+signing_key:
+specification_version: 4
+summary: 在 Ruby 檔案的第一行插入檔案路徑註解
+test_files: []