kotoshu 0.3.0

data/lib/kotoshu/core/models/result/document_result.rb

@@ -0,0 +1,263 @@
+# frozen_string_literal: true
+
+require_relative "word_result"
+
+module Kotoshu
+  module Models
+    module Result
+      # Result object for checking a document or file.
+      #
+      # This is a value object that represents the result of checking
+      # an entire document for spelling errors.
+      #
+      # @note This class is immutable and frozen on initialization.
+      #
+      # @example Creating a successful document result
+      #   result = DocumentResult.new(
+      #     file: "README.md",
+      #     errors: [],
+      #     word_count: 150
+      #   )
+      #   result.success?     # => true
+      #   result.error_count  # => 0
+      #
+      # @example Creating a result with errors
+      #   errors = [WordResult.incorrect("helo"), WordResult.incorrect("wrold")]
+      #   result = DocumentResult.new(
+      #     file: "document.txt",
+      #     errors: errors,
+      #     word_count: 100
+      #   )
+      #   result.success?     # => false
+      #   result.error_count  # => 2
+      class DocumentResult
+        # @return [String, nil] The file path (if applicable)
+        attr_reader :file
+
+        # @return [Array<WordResult>] List of spelling errors found
+        attr_reader :errors
+
+        # @return [Integer] Total word count
+        attr_reader :word_count
+
+        # @return [Hash] Additional metadata
+        attr_reader :metadata
+
+        # Create a new DocumentResult.
+        #
+        # @param file [String, nil] The file path (optional)
+        # @param errors [Array<WordResult>] List of errors
+        # @param word_count [Integer] Total word count
+        # @param metadata [Hash] Additional metadata (optional)
+        def initialize(file: nil, errors: [], word_count: 0, metadata: {})
+          @file = file&.dup&.freeze
+          @errors = errors.dup.freeze
+          @word_count = word_count
+          @metadata = metadata.dup.freeze
+
+          freeze
+        end
+
+        # Check if the document check was successful (no errors).
+        #
+        # @return [Boolean] True if no errors were found
+        def success?
+          @errors.empty?
+        end
+
+        # Check if the document check failed (has errors).
+        #
+        # @return [Boolean] True if errors were found
+        def failed?
+          !success?
+        end
+
+        # Get the number of errors found.
+        #
+        # @return [Integer] Error count
+        def error_count
+          @errors.size
+        end
+
+        # Get the number of unique errors (by word).
+        #
+        # @return [Integer] Unique error count
+        def unique_error_count
+          @errors.map(&:word).uniq.size
+        end
+
+        # Check if a specific word has an error.
+        #
+        # @param word [String] The word to check
+        # @return [Boolean] True if the word has an error
+        def has_error_for?(word)
+          @errors.any? { |e| e.word == word }
+        end
+
+        # Get errors for a specific word.
+        #
+        # @param word [String] The word
+        # @return [Array<WordResult>] Errors for the word
+        def errors_for(word)
+          @errors.select { |e| e.word == word }
+        end
+
+        # Iterate over errors.
+        #
+        # @yield [error] Each error
+        # @return [Enumerator] Enumerator if no block given
+        def each_error(&block)
+          return enum_for(:each_error) unless block_given?
+
+          @errors.each(&block)
+        end
+
+        # Iterate over unique error words.
+        #
+        # @yield [word, errors] Each unique word and its errors
+        # @return [Enumerator] Enumerator if no block given
+        def each_unique_error(&block)
+          return enum_for(:each_unique_error) unless block_given?
+
+          @errors.group_by(&:word).each(&block)
+        end
+
+        # Get the first N errors.
+        #
+        # @param n [Integer] Number of errors to return
+        # @return [Array<WordResult>] First N errors
+        def first_errors(n = 10)
+          @errors.first(n)
+        end
+
+        # Get error summary as a hash.
+        #
+        # @return [Hash] Summary of errors
+        def error_summary
+          summary = Hash.new(0)
+          each_error do |error|
+            summary[error.word] += 1
+          end
+          summary
+        end
+
+        # Convert to hash.
+        #
+        # @return [Hash] Hash representation
+        def to_h
+          {
+            file: @file,
+            success: success?,
+            word_count: @word_count,
+            error_count: error_count,
+            unique_error_count: unique_error_count,
+            errors: @errors.map(&:to_h),
+            error_summary: error_summary,
+            metadata: @metadata
+          }
+        end
+
+        # Convert to JSON-compatible hash.
+        #
+        # @return [Hash] JSON-compatible hash
+        def as_json
+          {
+            "file" => @file,
+            "success" => success?,
+            "wordCount" => @word_count,
+            "errorCount" => error_count,
+            "uniqueErrorCount" => unique_error_count,
+            "errors" => @errors.map(&:as_json),
+            "errorSummary" => error_summary,
+            "metadata" => @metadata
+          }
+        end
+
+        # Check equality based on file and errors.
+        #
+        # @param other [DocumentResult] The other result
+        # @return [Boolean] True if equal
+        def ==(other)
+          return false unless other.is_a?(DocumentResult)
+
+          @file == other.file && @errors == other.errors
+        end
+        alias eql? ==
+
+        # Hash based on file and errors.
+        #
+        # @return [Integer] Hash code
+        def hash
+          [@file, @errors].hash
+        end
+
+        # String representation.
+        #
+        # @return [String] String representation
+        def to_s
+          if success?
+            if @file
+              "File '#{@file}': No spelling errors found (#{@word_count} words checked)"
+            else
+              "No spelling errors found (#{@word_count} words checked)"
+            end
+          else
+            prefix = @file ? "File '#{@file}':" : ""
+            "#{prefix} #{error_count} spelling error(s) found " \
+            "(#{unique_error_count} unique) in #{@word_count} words"
+          end
+        end
+        alias inspect to_s
+
+        # Create a successful document result.
+        #
+        # @param file [String, nil] The file path (optional)
+        # @param word_count [Integer] Total word count
+        # @return [DocumentResult] New result indicating success
+        #
+        # @example
+        #   DocumentResult.success(file: "README.md", word_count: 150)
+        def self.success(file: nil, word_count: 0)
+          new(file: file, errors: [], word_count: word_count)
+        end
+
+        # Create a failed document result.
+        #
+        # @param file [String, nil] The file path (optional)
+        # @param errors [Array<WordResult>] List of errors
+        # @param word_count [Integer] Total word count
+        # @return [DocumentResult] New result indicating failure
+        #
+        # @example
+        #   errors = [WordResult.incorrect("helo"), WordResult.incorrect("wrold")]
+        #   DocumentResult.failure(file: "doc.txt", errors: errors, word_count: 100)
+        def self.failure(file: nil, errors: [], word_count: 0)
+          new(file: file, errors: errors, word_count: word_count)
+        end
+
+        # Merge multiple document results.
+        #
+        # @param results [Array<DocumentResult>] Results to merge
+        # @return [DocumentResult] Merged result
+        #
+        # @example Merging results from multiple files
+        #   result1 = DocumentResult.new(file: "file1.txt", errors: [e1], word_count: 50)
+        #   result2 = DocumentResult.new(file: "file2.txt", errors: [e2, e3], word_count: 75)
+        #   DocumentResult.merge([result1, result2])
+        #   # => DocumentResult with 3 errors and 125 words
+        def self.merge(results)
+          return new if results.empty?
+
+          all_errors = results.flat_map(&:errors)
+          total_words = results.sum(&:word_count)
+
+          new(
+            file: nil, # Merged results don't have a single file
+            errors: all_errors,
+            word_count: total_words
+          )
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/core/models/result/word_result.rb

@@ -0,0 +1,203 @@
+# frozen_string_literal: true
+
+require_relative "../../../suggestions/suggestion_set"
+
+module Kotoshu
+  module Models
+    module Result
+      # Result object for checking a single word.
+      #
+      # This is a value object that represents the result of checking
+      # a single word for spelling errors, including any suggestions.
+      #
+      # @note This class is immutable and frozen on initialization.
+      #
+      # @example Creating a correct word result
+      #   result = WordResult.new("hello", correct: true)
+      #   result.correct?     # => true
+      #   result.word         # => "hello"
+      #   result.suggestions  # => SuggestionSet.empty
+      #
+      # @example Creating an incorrect word result with suggestions
+      #   suggestions = SuggestionSet.from_words(%w[hello help], source: :test)
+      #   result = WordResult.new("helo", correct: false, suggestions: suggestions)
+      #   result.correct?     # => false
+      #   result.has_suggestions?  # => true
+      class WordResult
+        # @return [String] The word that was checked
+        attr_reader :word
+
+        # @return [Boolean] Whether the word is spelled correctly
+        attr_reader :correct
+
+        # @return [Suggestions::SuggestionSet] Suggestions for correction
+        attr_reader :suggestions
+
+        # @return [Integer] The position of the word in the source text (optional)
+        attr_reader :position
+
+        # @return [Hash] Additional metadata
+        attr_reader :metadata
+
+        # Create a new WordResult.
+        #
+        # @param word [String] The word that was checked
+        # @param correct [Boolean] Whether the word is correct
+        # @param suggestions [Suggestions::SuggestionSet] Suggestions (optional)
+        # @param position [Integer] Position in source text (optional)
+        # @param metadata [Hash] Additional metadata (optional)
+        def initialize(word, correct:, suggestions: nil, position: nil, metadata: {})
+          word = "" if word.nil?
+
+          @word = word.dup.freeze
+          @correct = correct
+          @suggestions = suggestions || Suggestions::SuggestionSet.empty
+          @position = position
+          @metadata = metadata.dup.freeze
+
+          freeze
+        end
+
+        # Check if the word is correct.
+        #
+        # @return [Boolean] True if the word is spelled correctly
+        def correct?
+          @correct
+        end
+
+        # Check if the word is incorrect.
+        #
+        # @return [Boolean] True if the word is misspelled
+        def incorrect?
+          !@correct
+        end
+
+        # Check if there are suggestions.
+        #
+        # @return [Boolean] True if suggestions are available
+        def has_suggestions?
+          !@suggestions.empty?
+        end
+
+        # Get the number of suggestions.
+        #
+        # @return [Integer] Number of suggestions
+        def suggestion_count
+          @suggestions.size
+        end
+
+        # Get the top N suggestions.
+        #
+        # @param n [Integer] Number of suggestions to return
+        # @return [Array<String>] Top N suggestion words
+        def top_suggestions(n = 3)
+          @suggestions.top(n).map(&:word)
+        end
+
+        # Get the first (best) suggestion.
+        #
+        # @return [String, nil] The best suggestion or nil
+        def first_suggestion
+          @suggestions.first&.word
+        end
+
+        # Convert to hash.
+        #
+        # @return [Hash] Hash representation
+        def to_h
+          {
+            word: @word,
+            correct: @correct,
+            position: @position,
+            suggestion_count: suggestion_count,
+            suggestions: top_suggestions(10),
+            metadata: @metadata
+          }
+        end
+
+        # Convert to JSON-compatible hash.
+        #
+        # @return [Hash] JSON-compatible hash
+        def as_json
+          {
+            "word" => @word,
+            "correct" => @correct,
+            "position" => @position,
+            "suggestionCount" => suggestion_count,
+            "suggestions" => top_suggestions(10),
+            "metadata" => @metadata
+          }
+        end
+
+        # Check equality based on word and correctness.
+        #
+        # @param other [WordResult] The other result
+        # @return [Boolean] True if equal
+        def ==(other)
+          return false unless other.is_a?(WordResult)
+
+          @word == other.word && @correct == other.correct
+        end
+        alias eql? ==
+
+        # Hash based on word and correctness.
+        #
+        # @return [Integer] Hash code
+        def hash
+          [@word, @correct].hash
+        end
+
+        # String representation.
+        #
+        # @return [String] String representation
+        def to_s
+          if @correct
+            @word
+          elsif has_suggestions?
+            "#{@word} (did you mean #{top_suggestions(3).join(", ")}?)"
+          else
+            "#{@word} (no suggestions)"
+          end
+        end
+        alias inspect to_s
+
+        # Create a correct word result.
+        #
+        # @param word [String] The word
+        # @param position [Integer] Position in source (optional)
+        # @return [WordResult] New result indicating correct spelling
+        #
+        # @example
+        #   WordResult.correct("hello")
+        def self.correct(word, position: nil)
+          new(word, correct: true, position: position)
+        end
+
+        # Create an incorrect word result with suggestions.
+        #
+        # @param word [String] The misspelled word
+        # @param suggestions [Suggestions::SuggestionSet, Array<String>] Suggestions
+        # @param position [Integer] Position in source (optional)
+        # @return [WordResult] New result indicating incorrect spelling
+        #
+        # @example With SuggestionSet
+        #   suggestions = SuggestionSet.from_words(%w[hello help], source: :test)
+        #   WordResult.incorrect("helo", suggestions: suggestions)
+        #
+        # @example With array of words
+        #   WordResult.incorrect("helo", suggestions: %w[hello help])
+        def self.incorrect(word, suggestions: nil, position: nil)
+          suggestions_set = if suggestions.is_a?(Suggestions::SuggestionSet)
+                              suggestions
+                            elsif suggestions.is_a?(Array)
+                              Suggestions::SuggestionSet.from_words(suggestions, source: :default)
+                            else
+                              Suggestions::SuggestionSet.empty
+                            end
+
+          new(word, correct: false, suggestions: suggestions_set, position: position)
+        end
+      end
+    end
+  end
+end

data/lib/kotoshu/core/models/word.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Models
+    # Word model representing a dictionary word with metadata.
+    #
+    # This is a value object that represents a word in the dictionary
+    # along with its morphological information (flags and data).
+    #
+    # @note This class is immutable and frozen on initialization.
+    #
+    # @example Creating a word
+    #   word = Models::Word.new("hello", flags: ["noun"], morphological_data: { root: "hell" })
+    #   word.text        # => "hello"
+    #   word.valid?      # => true
+    class Word
+      # @return [String] The word text
+      attr_reader :text
+
+      # @return [Array<String>] Morphological flags (e.g., "noun", "verb")
+      attr_reader :flags
+
+      # @return [Hash] Additional morphological data
+      attr_reader :morphological_data
+
+      # Create a new Word.
+      #
+      # @param text [String] The word text
+      # @param flags [Array<String>] Morphological flags (optional)
+      # @param morphological_data [Hash] Additional morphological data (optional)
+      def initialize(text, flags: [], morphological_data: {})
+        raise ArgumentError, "Text cannot be empty" if text.nil? || text.empty?
+
+        @text = text.dup.freeze
+        @flags = flags.dup.freeze
+        @morphological_data = morphological_data.dup.freeze
+
+        freeze
+      end
+
+      # Check if the word is valid (has content).
+      #
+      # @return [Boolean] True if the word is valid
+      def valid?
+        !@text.nil? && !@text.empty?
+      end
+
+      # Check if the word has a specific flag.
+      #
+      # @param flag [String] The flag to check
+      # @return [Boolean] True if the word has the flag
+      def has_flag?(flag)
+        @flags.include?(flag)
+      end
+
+      # Check if the word has any flags.
+      #
+      # @return [Boolean] True if the word has flags
+      def has_flags?
+        !@flags.empty?
+      end
+
+      # Get the length of the word.
+      #
+      # @return [Integer] Word length
+      def length
+        @text.length
+      end
+
+      # Check if the word is empty.
+      #
+      # @return [Boolean] True if the word is empty
+      def empty?
+        @text.empty?
+      end
+
+      # Convert to string.
+      #
+      # @return [String] The word text
+      def to_s
+        @text
+      end
+
+      # Convert to hash.
+      #
+      # @return [Hash] Hash representation
+      def to_h
+        {
+          text: @text,
+          flags: @flags,
+          morphological_data: @morphological_data
+        }
+      end
+
+      # Check equality based on text.
+      #
+      # @param other [Word, String] The other object
+      # @return [Boolean] True if equal
+      def ==(other)
+        return false unless other.is_a?(Word)
+
+        @text == other.text
+      end
+      alias eql? ==
+
+      # Hash based on text.
+      #
+      # @return [Integer] Hash code
+      def hash
+        @text.hash
+      end
+
+      # Compare words by text.
+      #
+      # @param other [Word] The other word
+      # @return [Integer] Comparison result
+      def <=>(other)
+        return nil unless other.is_a?(Word)
+
+        @text <=> other.text
+      end
+
+      # Create a word from a Hunspell dictionary line.
+      #
+      # @param line [String] Dictionary line (e.g., "hello/flag" or "hello")
+      # @return [Word] New word instance
+      #
+      # @example
+      #   Word.from_dic_line("hello/N")  # => Word with text "hello" and flag "N"
+      #   Word.from_dic_line("hello")    # => Word with text "hello" and no flags
+      def self.from_dic_line(line)
+        return nil if line.nil? || line.empty?
+
+        parts = line.split("/", 2)
+        text = parts[0]
+        flags = parts[1] ? parts[1].split("") : []
+
+        new(text, flags: flags)
+      end
+    end
+  end
+end