rubocop-spellcheck 0.1.0

data/lib/rubocop/cop/spellcheck/spelling.rb

@@ -0,0 +1,131 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Cop
+    module Spellcheck
+      # Checks Ruby comments, Markdown prose, and plain text with shared dictionaries.
+      class Spelling < Base
+        BUNDLED_DATA = File.expand_path('../../../../data', __dir__).freeze
+        DIRECTIVE = /
+          \A\#\s*(?:!|(?:rubocop|standard|coding|encoding|frozen_string_literal|
+          warn_indent|shareable_constant_value|typed)\s*:)|\A\#.*-\*-\s*(?:coding|encoding):
+        /x
+        ADDRESS = %r{(?:https?://|www\.)[^\s<>]+|[\w.+-]+@[\w.-]+\.[a-zA-Z]{2,}}
+
+        def on_new_investigation
+          super
+          if RuboCop::Spellcheck::Markdown.file?(processed_source.path)
+            check_markdown
+          else
+            processed_source.comments.each do |comment|
+              next if DIRECTIVE.match?(comment.text)
+
+              check_comment(comment)
+            end
+          end
+        end
+
+        def on_other_file
+          if RuboCop::Spellcheck::ProseSource.text_file?(processed_source.path)
+            check_text
+          elsif RuboCop::Spellcheck::Markdown.file?(processed_source.path)
+            check_markdown
+          else
+            super
+          end
+        end
+
+        def relevant_file?(file)
+          return false unless super
+          return false if File.expand_path(file).start_with?("#{BUNDLED_DATA}/")
+          return true unless RuboCop::Spellcheck::ProseSource.text_file?(file)
+
+          !checker.dictionary_file?(file)
+        end
+
+        def external_dependency_checksum
+          checker.checksum
+        end
+
+        private
+
+        def front_matter_enabled?
+          cop_config.fetch('Markdown', {}).fetch('FrontMatter', {}).fetch('Enabled', true)
+        end
+
+        def check_markdown
+          if front_matter_enabled?
+            RuboCop::Spellcheck::FrontMatter.new(prose_buffer).each_span do |text, positions|
+              check_markdown_span(text, positions)
+            end
+          end
+          RuboCop::Spellcheck::Markdown.new(prose_buffer).each_span do |text, positions|
+            check_markdown_span(text, positions)
+          end
+        end
+
+        def check_text
+          checker.misspellings(mask_addresses(processed_source.buffer.source)).each do |word, position|
+            next unless word.match?(/\p{L}/)
+
+            report_word(word, position, position + word.length)
+          end
+        end
+
+        def checker
+          @checker ||= RuboCop::Spellcheck::Checker.new(
+            dictionary_files: cop_config['DictionaryFiles'],
+            base_directory: config.base_dir_for_path_parameters
+          )
+        end
+
+        def check_comment(comment)
+          checker.misspellings(prose(comment.text)).each do |word, position|
+            first = comment.source_range.begin_pos + position
+            report_word(word, first, first + word.length)
+          end
+        end
+
+        def check_markdown_span(text, positions)
+          text = text.sub(/\A['’]s\b/, '  ')
+          checker.misspellings(mask_addresses(text)).each do |word, position|
+            next unless word.match?(/\p{L}/)
+
+            report_word(word, positions.fetch(position).first, positions.fetch(position + word.length - 1).last)
+          end
+        end
+
+        def report_word(word, first, last)
+          range = Parser::Source::Range.new(prose_buffer, first, last)
+          range = markdown_document.processed_range(range) if markdown_document
+          add_offense(range, message: spelling_message(word))
+        end
+
+        def markdown_document
+          processed_source.markdown_document if processed_source.respond_to?(:markdown_document)
+        end
+
+        def prose_buffer
+          markdown_document ? markdown_document.buffer : processed_source.buffer
+        end
+
+        def prose(text)
+          # Preserve character offsets while removing non-prose addresses and block delimiters.
+          mask_addresses(text).gsub(/^=(?:begin|end)\b[^\n]*/) { |marker| ' ' * marker.length }
+        end
+
+        def mask_addresses(text)
+          text.gsub(ADDRESS) { |address| ' ' * address.length }
+        end
+
+        def spelling_message(word)
+          suggestions = checker.suggestions(word)
+          message = "Misspelled word: `#{word}`."
+          return message if suggestions.empty?
+
+          "#{message} Did you mean #{suggestions.map { |suggestion| "`#{suggestion}`" }.join(', ')}?"
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/spellcheck/checker.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require 'digest'
+require 'kotoshu'
+require 'pathname'
+
+module RuboCop
+  module Spellcheck
+    # Checks words against explicitly selected, local language dictionaries.
+    class Checker
+      DEFAULT_FILES = { 'en' => ['gem:rubocop-spellcheck/data/en/en.dic'].freeze }.freeze
+      ENGLISH_WORD = /(?<![\p{L}\p{M}\p{N}_])[\p{Latin}\p{M}]+(?:['’][\p{Latin}\p{M}]+)*(?![\p{L}\p{M}\p{N}_])/
+
+      def initialize(dictionary_files: nil, base_directory: Dir.pwd)
+        @base_directory = base_directory
+        @paths = []
+        @checkers = build_checkers(dictionary_files.nil? ? DEFAULT_FILES : dictionary_files)
+        @verdicts = {}
+        @suggestions = {}
+        @checksum = Digest::SHA256.hexdigest(
+          [Kotoshu::VERSION, *@paths.map { |path| Digest::SHA256.file(path).hexdigest }].join("\0")
+        )
+      end
+
+      attr_reader :checksum
+
+      def dictionary_file?(path)
+        return false unless File.exist?(path)
+
+        @paths.any? { |dictionary| File.identical?(dictionary, path) }
+      end
+
+      def misspellings(text)
+        @checkers.flat_map { |checker| tokens(checker, text) }.uniq
+                 .sort_by(&:last).reject { |word, _position| correct?(word) }
+      end
+
+      def suggestions(word)
+        @suggestions[word] ||= @checkers.flat_map do |checker|
+          checker.suggest(word, max_suggestions: 3).to_words
+        end.uniq.first(3)
+      end
+
+      private
+
+      def tokens(checker, text)
+        return checker.tokenize(text) unless checker.config.language.match?(/\Aen(?:[-_]|\z)/i)
+
+        text.to_enum(:scan, ENGLISH_WORD).map { [Regexp.last_match[0], Regexp.last_match.begin(0)] }
+      end
+
+      def build_checkers(files)
+        validate!(files)
+        files.flat_map do |language, paths|
+          paths.map { |path| build_checker(language, resolve_path(path)) }
+        end
+      end
+
+      def validate!(files)
+        valid = files.is_a?(Hash) && !files.empty? &&
+                files.all? { |language, paths| valid_language?(language) && valid_paths?(paths) }
+        return if valid
+
+        raise RuboCop::ValidationError, 'Spellcheck/DictionaryFiles must map language codes to nonempty lists of paths.'
+      end
+
+      def valid_language?(language)
+        language.is_a?(String) && language.match?(/\A[a-zA-Z]+(?:[-_][a-zA-Z0-9]+)*\z/)
+      end
+
+      def valid_paths?(paths)
+        paths.is_a?(Array) && !paths.empty? && paths.all? { |path| path.is_a?(String) && !path.empty? }
+      end
+
+      def resolve_path(path)
+        return File.expand_path(path, @base_directory) unless path.start_with?('gem:')
+
+        match = %r{\Agem:([^/]+)/(.+)\z}.match(path)
+        raise RuboCop::ValidationError, "Invalid gem dictionary path: #{path}" unless match
+
+        root = Gem::Specification.find_by_name(match[1]).full_gem_path
+        resolved = File.expand_path(match[2], root)
+        raise RuboCop::ValidationError, "Path escapes gem: #{path}" unless resolved.start_with?("#{root}/")
+
+        resolved
+      rescue Gem::LoadError => e
+        raise RuboCop::ValidationError, "Cannot resolve dictionary #{path}: #{e.message}"
+      end
+
+      def build_checker(language, path)
+        dictionary = load_dictionary(language, path)
+        settings = Kotoshu::Configuration.new(
+          language: language, offline: true, personal_dictionary: false, backend: 'ruby'
+        )
+        Kotoshu::Spellchecker.new(dictionary: dictionary, config: settings)
+      end
+
+      def load_dictionary(language, path)
+        case File.extname(path)
+        when '.dic'
+          hunspell_dictionary(language, path)
+        when '.txt'
+          words = read_file(path).lines.filter_map { |line| dictionary_word(line, path) }
+          Kotoshu::Dictionary::PlainText.from_words(words, language_code: language)
+        else
+          raise RuboCop::ValidationError, "Expected a .dic or .txt dictionary: #{path}"
+        end
+      end
+
+      def hunspell_dictionary(language, path)
+        aff = path.sub(/\.dic\z/, '.aff')
+        [path, aff].each { |file| read_file(file) }
+        Kotoshu::Dictionary::Hunspell.new(dic_path: path, aff_path: aff, language_code: language)
+      end
+
+      def read_file(path)
+        content = File.read(path, encoding: 'UTF-8')
+        @paths << path
+        content
+      rescue SystemCallError => e
+        raise RuboCop::ValidationError, "Cannot read spelling dictionary #{path}: #{e.message}"
+      end
+
+      def dictionary_word(line, path)
+        word = line.strip
+        return if word.empty? || word.start_with?('#')
+        raise RuboCop::ValidationError, "Expected one word per line in #{path}: #{word.inspect}" if word.match?(/\s/)
+
+        word
+      end
+
+      def correct?(word)
+        return @verdicts[word] if @verdicts.key?(word)
+
+        @verdicts[word] = @checkers.any? { |checker| checker.correct?(word) }
+      end
+    end
+  end
+end

data/lib/rubocop/spellcheck/front_matter.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require 'psych'
+require 'date'
+
+module RuboCop
+  module Spellcheck
+    # Reads YAML string values without constructing application objects.
+    class FrontMatter
+      HEADER = /\A(?:\uFEFF)?---[ \t]*\n.*?^(?:---|\.\.\.)[ \t]*(?:\n|\z)/m
+      ESCAPE = /\\(?:U[0-9a-fA-F]{8}|u[0-9a-fA-F]{4}|x[0-9a-fA-F]{2}|.)/m
+
+      def initialize(buffer)
+        @buffer = buffer
+        @scanner = Psych::ScalarScanner.new(Psych::ClassLoader.new)
+      end
+
+      def each_span
+        return enum_for(__method__) unless block_given?
+
+        root = yaml_root
+        string_values(root) { |node| yield scalar_span(node) } if root
+      end
+
+      private
+
+      def yaml_root
+        return unless (header = HEADER.match(@buffer.source))
+
+        yaml = header[0].sub(/^(?:---|\.\.\.)[ \t]*\n?\z/, '')
+        Psych.parse_stream(yaml).children.first&.root
+      rescue Psych::SyntaxError => e
+        raise RuboCop::ValidationError, "Invalid YAML front matter in #{@buffer.name}: #{e.message}"
+      end
+
+      def string_values(node, &block)
+        case node
+        when Psych::Nodes::Mapping
+          node.children.each_slice(2) { |_key, value| string_values(value, &block) }
+        when Psych::Nodes::Sequence
+          node.children.each { |value| string_values(value, &block) }
+        when Psych::Nodes::Scalar
+          yield node if string_scalar?(node)
+        end
+      end
+
+      def string_scalar?(node)
+        return node.tag == 'tag:yaml.org,2002:str' if node.tag
+        return true unless node.plain
+
+        @scanner.tokenize(node.value).is_a?(String)
+      end
+
+      def position(line, column)
+        @buffer.line_range(line + 1).begin_pos + column
+      end
+
+      def scalar_span(node)
+        first = position(node.start_line, node.start_column)
+        last = position(node.end_line, node.end_column)
+        raw = @buffer.source[first...last]
+        prefix = raw[/\A(?:(?:&\S+|!\S+)[ \t]+)+/].to_s.length
+        map_pieces(raw[prefix..], node.style, first + prefix)
+      end
+
+      def map_pieces(raw, style, first)
+        text = +''
+        positions = []
+        scalar_pieces(raw, style).each do |piece, offset, decoded|
+          text << decoded
+          decoded.length.times { positions << [first + offset, first + offset + piece.length] }
+        end
+        [text, positions]
+      end
+
+      def scalar_pieces(raw, style)
+        return enum_for(__method__, raw, style) unless block_given?
+
+        pattern = style == Psych::Nodes::Scalar::DOUBLE_QUOTED ? /#{ESCAPE}|./m : /''|./m
+        raw.to_enum(:scan, pattern).each do
+          match = Regexp.last_match
+          piece = match[0]
+          decoded = decode(piece, style)
+          decoded = ' ' * piece.length if ignored_piece?(raw, match.begin(0), style)
+          yield piece, match.begin(0), decoded
+        end
+      end
+
+      def ignored_piece?(raw, offset, style)
+        case style
+        when Psych::Nodes::Scalar::LITERAL, Psych::Nodes::Scalar::FOLDED
+          offset < raw.index("\n").to_i
+        when Psych::Nodes::Scalar::SINGLE_QUOTED, Psych::Nodes::Scalar::DOUBLE_QUOTED
+          offset.zero? || offset == raw.length - 1
+        else
+          false
+        end
+      end
+
+      def decode(piece, style)
+        if style == Psych::Nodes::Scalar::DOUBLE_QUOTED && piece.start_with?('\\')
+          Psych.safe_load("\"#{piece}\"") || ''
+        elsif style == Psych::Nodes::Scalar::SINGLE_QUOTED && piece == "''"
+          "'"
+        else
+          piece
+        end
+      end
+    end
+  end
+end

data/lib/rubocop/spellcheck/markdown.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'commonmarker'
+
+module RuboCop
+  module Spellcheck
+    # Extracts visible text while retaining character ranges in the original source.
+    class Markdown
+      EXTENSIONS = %w[.md .markdown].freeze
+      ENTITY = /&(?:\#x[0-9a-f]+|\#\d+|[a-z][a-z0-9]+);/i
+      PIECE = /#{ENTITY}|\\[[:punct:]]|./m
+      LIQUID = /\{\{.*?\}\}|\{%.*?%\}/m
+
+      def self.file?(path)
+        path && EXTENSIONS.include?(File.extname(path).downcase)
+      end
+
+      def initialize(buffer)
+        @buffer = buffer
+        @lines = buffer.source.lines
+      end
+
+      def each_span
+        return enum_for(__method__) unless block_given?
+
+        document = Commonmarker.parse(parser_source, options: {
+                                        parse: { smart: false },
+                                        extension: { shortcodes: false, footnotes: true }
+                                      })
+        document.walk do |node|
+          next unless node.type == :text
+
+          text, positions = mapped_text(node)
+          yield text, positions unless text.empty?
+        end
+      end
+
+      private
+
+      def parser_source
+        without_front_matter.gsub(LIQUID) do |expression|
+          expression.gsub(/[^\n]/) { |character| 'x' * character.bytesize }
+        end
+      end
+
+      def without_front_matter
+        @buffer.source.sub(/\A(?:\uFEFF)?---[ \t]*\n.*?^(?:---|\.\.\.)[ \t]*(?:\n|\z)/m) do |header|
+          header.gsub(/[^\n]/, ' ')
+        end
+      end
+
+      def character_position(line, byte_column)
+        prefix = @lines.fetch(line - 1).byteslice(0, byte_column)
+        @buffer.line_range(line).begin_pos + prefix.length
+      end
+
+      def mapped_text(node)
+        location = node.source_position
+        first = character_position(location.fetch(:start_line), location.fetch(:start_column) - 1)
+        last = character_position(location.fetch(:end_line), location.fetch(:end_column))
+        decode_text(@buffer.source[first...last], first)
+      end
+
+      def decode_text(raw, first)
+        raw = without_liquid(raw)
+        text = +''
+        positions = []
+        raw.to_enum(:scan, PIECE).each do
+          match = Regexp.last_match
+          decoded = decode(match[0])
+          text << decoded
+          decoded.length.times { positions << [first + match.begin(0), first + match.end(0)] }
+        end
+        [text, positions]
+      end
+
+      def without_liquid(raw)
+        raw.gsub(LIQUID) { |expression| expression.gsub(/[^\n]/, ' ') }
+      end
+
+      def decode(piece)
+        return piece.delete_prefix('\\') if piece.start_with?('\\')
+        return piece unless ENTITY.match?(piece)
+
+        document = Commonmarker.parse(piece, options: { parse: { smart: false } })
+        document.walk.select { |node| node.type == :text }.map(&:string_content).join
+      end
+    end
+  end
+end

data/lib/rubocop/spellcheck/plugin.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'lint_roller'
+
+module RuboCop
+  module Spellcheck
+    # Registers the extension and its defaults with RuboCop.
+    class Plugin < LintRoller::Plugin
+      def about
+        LintRoller::About.new(
+          name: 'rubocop-spellcheck',
+          version: VERSION,
+          homepage: 'https://github.com/dblock/rubocop-spellcheck',
+          description: 'Spellcheck Ruby comments, Markdown prose, and plain text.'
+        )
+      end
+
+      def supported?(context)
+        context.engine == :rubocop
+      end
+
+      def rules(_context)
+        LintRoller::Rules.new(
+          type: :path, config_format: :rubocop,
+          value: Pathname.new(__dir__).join('../../../config/default.yml')
+        )
+      end
+    end
+  end
+end

data/lib/rubocop/spellcheck/prose_source.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Spellcheck
+    # Prose files use the non-Ruby callback, with an untouched source buffer.
+    module ProseSource
+      def self.file?(path)
+        Markdown.file?(path) || text_file?(path)
+      end
+
+      def self.text_file?(path)
+        path && File.extname(path).downcase == '.txt'
+      end
+
+      def valid_syntax?
+        ProseSource.file?(path) && !markdown_preprocessor? ? false : super
+      end
+
+      private
+
+      def parse(source, *)
+        return super if !ProseSource.file?(path) || markdown_preprocessor?
+
+        super('', *)
+        @buffer = Parser::Source::Buffer.new(path, source: source)
+      end
+
+      def markdown_preprocessor?
+        Markdown.file?(path) && respond_to?(:markdown_document)
+      end
+    end
+  end
+end
+
+RuboCop::ProcessedSource.prepend(RuboCop::Spellcheck::ProseSource)

data/lib/rubocop/spellcheck/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module RuboCop
+  module Spellcheck
+    VERSION = '0.1.0'
+  end
+end

data/lib/rubocop-spellcheck.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'rubocop'
+require_relative 'rubocop/spellcheck/version'
+require_relative 'rubocop/spellcheck/plugin'
+require_relative 'rubocop/spellcheck/checker'
+require_relative 'rubocop/spellcheck/front_matter'
+require_relative 'rubocop/spellcheck/markdown'
+require_relative 'rubocop/spellcheck/prose_source'
+require_relative 'rubocop/cop/spellcheck/spelling'

metadata

@@ -0,0 +1,128 @@
+--- !ruby/object:Gem::Specification
+name: rubocop-spellcheck
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel (dB.) Doubrovkine
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-10-20 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: commonmarker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: kotoshu
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.8
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.0.8
+- !ruby/object:Gem::Dependency
+  name: lint_roller
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.72.1
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.72'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.72.1
+description: RuboCop spelling checks for Ruby comments, Markdown, and plain text,
+  using offline dictionaries.
+email:
+- dblock@dblock.org
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- config/default.yml
+- data/en/LICENSE
+- data/en/README.md
+- data/en/en.aff
+- data/en/en.dic
+- lib/rubocop-spellcheck.rb
+- lib/rubocop/cop/spellcheck/spelling.rb
+- lib/rubocop/spellcheck/checker.rb
+- lib/rubocop/spellcheck/front_matter.rb
+- lib/rubocop/spellcheck/markdown.rb
+- lib/rubocop/spellcheck/plugin.rb
+- lib/rubocop/spellcheck/prose_source.rb
+- lib/rubocop/spellcheck/version.rb
+homepage: https://github.com/dblock/rubocop-spellcheck
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  source_code_uri: https://github.com/dblock/rubocop-spellcheck
+  changelog_uri: https://github.com/dblock/rubocop-spellcheck/blob/master/CHANGELOG.md
+  bug_tracker_uri: https://github.com/dblock/rubocop-spellcheck/issues
+  rubygems_mfa_required: 'true'
+  default_lint_roller_plugin: RuboCop::Spellcheck::Plugin
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.2'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.16
+signing_key:
+specification_version: 4
+summary: Spellcheck Ruby comments, Markdown, and plain text with RuboCop.
+test_files: []