kotoshu 0.3.0

data/lib/kotoshu/cache/suggestion_cache.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "lookup_cache"
+
+module Kotoshu
+  module Cache
+    # LRU cache specifically for suggestion results.
+    #
+    # Extends LookupCache with suggestion-specific features like
+    # caching by word + max_results combination.
+    #
+    # @example Caching suggestions
+    #   cache = SuggestionCache.new(max_size: 5000)
+    #   cache.write("helo", ["hello", "help"], max_results: 10)
+    #   cache.read("helo", max_results: 10)  # => ["hello", "help"]
+    class SuggestionCache < LookupCache
+      # Default maximum cache size for suggestions
+      DEFAULT_MAX_SIZE = 5000
+
+      # Create a new suggestion cache.
+      #
+      # @param max_size [Integer] Maximum number of entries (default: 5000)
+      def initialize(max_size: DEFAULT_MAX_SIZE)
+        super(max_size: max_size)
+      end
+
+      # Write suggestions to cache.
+      #
+      # @param word [String] The misspelled word
+      # @param suggestions [Array<String>] Suggested words
+      # @param max_results [Integer] Max results used for this query
+      # @return [Array<String>] The stored suggestions
+      def write(word, suggestions, max_results: 10)
+        cache_key = cache_key_for(word, max_results)
+        super(cache_key, suggestions)
+      end
+
+      # Read suggestions from cache.
+      #
+      # @param word [String] The misspelled word
+      # @param max_results [Integer] Max results used for this query
+      # @return [Array<String>, nil] Cached suggestions or nil
+      def read(word, max_results: 10)
+        cache_key = cache_key_for(word, max_results)
+        super(cache_key)
+      end
+
+      # Fetch suggestions from cache or compute them.
+      #
+      # @param word [String] The misspelled word
+      # @param max_results [Integer] Max results for this query
+      # @yield Block to compute suggestions on cache miss
+      # @return [Array<String>] Cached or computed suggestions
+      def fetch(word, max_results: 10)
+        cache_key = cache_key_for(word, max_results)
+
+        if @data.key?(cache_key)
+          record_hit
+          @access_order += 1
+          @data[cache_key][1] = @access_order # Update access order
+          @data[cache_key][0] # Return value
+        else
+          record_miss
+          suggestions = yield
+          write(word, suggestions, max_results: max_results)
+          suggestions
+        end
+      end
+
+      # Delete suggestions from cache.
+      #
+      # @param word [String] The misspelled word
+      # @param max_results [Integer] Max results for this query
+      # @return [Array<String>, nil] Deleted suggestions or nil
+      def delete(word, max_results: 10)
+        cache_key = cache_key_for(word, max_results)
+        super(cache_key)
+      end
+
+      # Check if suggestions are cached for this word.
+      #
+      # @param word [String] The misspelled word
+      # @param max_results [Integer] Max results for this query
+      # @return [Boolean] True if cached
+      def key?(word, max_results: 10)
+        cache_key = cache_key_for(word, max_results)
+        super(cache_key)
+      end
+
+      # Invalidate all cached suggestions for a word.
+      #
+      # @param word [String] The word to invalidate
+      # @return [self] Self for chaining
+      def invalidate_word(word)
+        # Find and delete all cache entries for this word
+        keys_to_delete = @data.keys.select { |key| key.start_with?("#{word}|") }
+        keys_to_delete.each { |key| @data.delete(key) }
+        self
+      end
+
+      private
+
+      # Generate cache key for word + max_results.
+      #
+      # @param word [String] The word
+      # @param max_results [Integer] Max results
+      # @return [String] Cache key
+      def cache_key_for(word, max_results)
+        "#{word.downcase}|#{max_results}"
+      end
+    end
+  end
+end

data/lib/kotoshu/cache.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative 'cache/cache'
+require_relative 'cache/language_cache'
+require_relative 'cache/model_cache'
+
+module Kotoshu
+  # Cache module for Kotoshu
+  #
+  # This module provides access to various cache implementations for
+  # dictionaries, models, and other resources.
+  #
+  # @example Using the language cache
+  #   cache = Kotoshu::Cache::LanguageCache.new
+  #   dict = cache.get_spelling('en')
+  #   # => { dic_path: "~/.cache/kotoshu/languages/en/spelling/index.dic",
+  #   #      aff_path: "~/.cache/kotoshu/languages/en/spelling/index.aff",
+  #   #      metadata: { ... } }
+  #
+  module Cache
+    class << self
+      # Create a new language cache instance
+      #
+      # @param cache_path [String] optional custom cache directory
+      # @param url_base [String] optional custom GitHub URL
+      # @return [LanguageCache] new language cache instance
+      def language_cache(cache_path: nil, url_base: nil)
+        LanguageCache.new(cache_path: cache_path, url_base: url_base)
+      end
+
+      # Create a new model cache instance
+      #
+      # @param cache_path [String] optional custom cache directory
+      # @return [ModelCache] new model cache instance
+      def model_cache(cache_path: nil)
+        ModelCache.new(cache_path: cache_path)
+      end
+    end
+  end
+end

data/lib/kotoshu/cli/auto_setup.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require "io/console"
+
+module Kotoshu
+  module Cli
+    # Interactive prompt that wraps the strict two-stage setup/resolve flow
+    # for the human-facing CLI.
+    #
+    # The library API (`Kotoshu.correct?`, `Kotoshu.suggest`) still raises
+    # `ResourceNotSetupError` strictly — no surprise downloads on metered
+    # networks. This class catches that error in the CLI dispatcher, asks
+    # the user once, and retries the original command. Programmatic users
+    # never see it.
+    #
+    # Non-TTY contexts (pipes, CI) and offline mode never prompt. The caller
+    # decides how to surface a nil result — the CLI dispatcher raises
+    # Errors::ResourceUnavailable so scripts see stable exit codes.
+    class AutoSetup
+      # @param input [IO] Stdin (or override for tests)
+      # @param output [IO] Stderr (or override for tests)
+      def initialize(input: $stdin, output: $stderr)
+        @input = input
+        @output = output
+      end
+
+      # Prompt the user to set up the missing language.
+      #
+      # @param error [Kotoshu::ResourceNotSetupError] The error raised by resolve
+      # @param want [Array<Symbol>] Resource types to fetch (default [:spelling])
+      # @return [String, nil] Language code on success; nil when non-TTY,
+      #   offline, or user declined.
+      def call(error, want: %i[spelling])
+        language = error.language
+        return nil if skip_prompt?
+
+        @output.puts prompt_message(language, error.resource_type, want)
+        answer = @input.gets&.strip&.downcase
+        return nil unless affirmative?(answer)
+
+        Kotoshu.setup(language, want: want)
+        language
+      end
+
+      private
+
+      def skip_prompt?
+        Kotoshu.configuration.offline || !@input.tty?
+      end
+
+      def prompt_message(language, resource, want)
+        size_hint = size_hint_for(want)
+        "Language '#{language}' is not set up (missing #{resource}).\n" \
+          "Download now (~#{size_hint} from github.com/kotoshu/dictionaries)? [Y/n]"
+      end
+
+      def size_hint_for(want)
+        case want
+        when %i[spelling] then "5 MB"
+        when %i[spelling frequency] then "6 MB"
+        when %i[spelling frequency model] then "120 MB"
+        else "unknown size"
+        end
+      end
+
+      def affirmative?(answer)
+        answer.nil? || answer.empty? || answer.start_with?("y")
+      end
+    end
+  end
+end

data/lib/kotoshu/cli/batch_reporter.rb

@@ -0,0 +1,315 @@
+# frozen_string_literal: true
+
+require_relative 'display_formatter'
+require_relative 'navigation_manager'
+require 'json'
+require 'csv'
+
+module Kotoshu
+  module Cli
+    # Batch reporter for non-interactive error reporting.
+    #
+    # Outputs error reports in various formats (JSON, YAML, CSV, text).
+    # Used for automated checking and CI/CD integration.
+    #
+    # @example Generate JSON report
+    #   reporter = BatchReporter.new(document, navigation)
+    #   reporter.to_json('errors.json')
+    #
+    # @example Generate CSV report
+    #   reporter.to_csv('errors.csv')
+    #
+    # @example Generate text summary
+    #   puts reporter.to_text
+    class BatchReporter
+      attr_reader :document, :navigation, :formatter
+
+      # Create a new batch reporter.
+      #
+      # @param document [Documents::Document] Document being reported
+      # @param navigation [NavigationManager] Navigation state
+      # @param formatter [DisplayFormatter, nil] Display formatter
+      def initialize(document, navigation, formatter: nil)
+        @document = document
+        @navigation = navigation
+        @formatter = formatter || DisplayFormatter.new
+      end
+
+      # Generate JSON report.
+      #
+      # @param filepath [String] Output file path (optional, returns string if nil)
+      # @param pretty [Boolean] Pretty-print JSON (default: true)
+      # @return [String, nil] JSON string or nil if written to file
+      def to_json(filepath: nil, pretty: true)
+        data = generate_report_data
+        json = pretty ? JSON.pretty_generate(data) : JSON.generate(data)
+
+        if filepath
+          File.write(filepath, json)
+          nil
+        else
+          json
+        end
+      end
+
+      # Generate YAML report.
+      #
+      # @param filepath [String] Output file path (optional, returns string if nil)
+      # @return [String, nil] YAML string or nil if written to file
+      def to_yaml(filepath: nil)
+        require 'yaml'
+
+        data = generate_report_data
+        yaml = data.to_yaml
+
+        if filepath
+          File.write(filepath, yaml)
+          nil
+        else
+          yaml
+        end
+      end
+
+      # Generate CSV report.
+      #
+      # @param filepath [String] Output file path (optional, returns string if nil)
+      # @return [String, nil] CSV string or nil if written to file
+      def to_csv(filepath: nil)
+        csv_string = CSV.generate do |csv|
+          # Header
+          csv << ['ID', 'Line', 'Original', 'Suggestion', 'Confidence', 'Error Type']
+
+          # Data rows
+          @navigation.errors.each do |error|
+            suggestion = error.recommended_suggestion
+            csv << [
+              error.id,
+              error.location.line,
+              error.original,
+              suggestion&.word || '',
+              "#{(error.confidence * 100).round(1)}%",
+              error.error_type.to_s.capitalize
+            ]
+          end
+        end
+
+        if filepath
+          File.write(filepath, csv_string)
+          nil
+        else
+          csv_string
+        end
+      end
+
+      # Generate text summary.
+      #
+      # @return [String] Formatted text summary
+      def to_text
+        lines = []
+        lines << ""
+        lines << @formatter.colorize("╔═══════════════════════════════════════════════════════════════╗", :bold)
+        lines << @formatter.colorize("║                    Batch Error Report                        ║", :bold)
+        lines << @formatter.colorize("╚═══════════════════════════════════════════════════════════════╝", :bold)
+        lines << ""
+        lines << "Document: #{@document.name}"
+        lines << "Format: #{Documents::Document::FORMATS[@document.format]}"
+        lines << "Language: #{@document.language_code}"
+        lines << ""
+        lines << @formatter.colorize("Summary", :bold)
+        lines << "─" * 70
+
+        stats = @navigation.statistics
+        lines << "Total errors: #{stats[:total]}"
+        lines << "  • High confidence (>0.8): #{stats[:by_confidence][:high]}"
+        lines << "  • Medium confidence (0.5-0.8): #{stats[:by_confidence][:medium]}"
+        lines << "  • Low confidence (≤0.5): #{stats[:by_confidence][:low]}"
+        lines << ""
+
+        # Breakdown by type
+        if stats[:by_type]&.any?
+          lines << @formatter.colorize("By Type", :bold)
+          stats[:by_type].each do |type, count|
+            label = Models::SemanticError::ERROR_TYPES[type] || type.to_s.capitalize
+            lines << "  • #{label}: #{count}"
+          end
+          lines << ""
+        end
+
+        # Top errors
+        if @navigation.errors.any?
+          lines << @formatter.colorize("Top Errors", :bold)
+          lines << "─" * 70
+
+          @navigation.errors.first(10).each_with_index do |error, idx|
+            lines << "#{idx + 1}. [#{error.location}] #{error.original}"
+            lines << "   Type: #{error.error_type}"
+            lines << "   Confidence: #{(error.confidence * 100).round(1)}%"
+
+            if error.suggestions&.any?
+              top_suggestion = error.suggestions.first
+              lines << "   Suggestion: #{top_suggestion.word} (#{(top_suggestion.confidence * 100).round(0)}%)"
+            end
+
+            lines << ""
+          end
+
+          if @navigation.errors.size > 10
+            lines << "... and #{@navigation.errors.size - 10} more"
+            lines << ""
+          end
+        end
+
+        lines.join("\n")
+      end
+
+      # Generate SARIF report (Static Analysis Results Interchange Format).
+      #
+      # SARIF is a standard format for static analysis tools.
+      # Useful for CI/CD integration and IDE integration.
+      #
+      # @param filepath [String] Output file path (optional, returns string if nil)
+      # @return [String, nil] SARIF JSON string or nil if written to file
+      def to_sarif(filepath: nil)
+        sarif = {
+          version: "2.1.0",
+          "$schema": "https://json.schemastore.org/sarif-2.1.0.json",
+          runs: [
+            {
+              tool: {
+                driver: {
+                  name: "Kotoshu",
+                  version: Kotoshu::VERSION,
+                  informationUri: "https://github.com/kotoshu/kotoshu",
+                  rules: []
+                }
+              },
+              results: @navigation.errors.map do |error|
+                {
+                  ruleId: error.error_type.to_s,
+                  level: error.high_confidence? ? "error" : "warning",
+                  message: {
+                    text: "Potential #{error.error_type} error: '#{error.original}'"
+                  },
+                  locations: [
+                    {
+                      physicalLocation: {
+                        artifactLocation: {
+                          uri: @document.name
+                        },
+                        region: {
+                          startLine: error.location.line || 1,
+                          startColumn: error.location.column || 0
+                        }
+                      }
+                    }
+                  ],
+                  suggestions: error.suggestions&.map do |sugg|
+                    {
+                      text: sugg.word
+                    }
+                  end
+                }
+              end
+            }
+          ]
+        }
+
+        json = JSON.pretty_generate(sarif)
+
+        if filepath
+          File.write(filepath, json)
+          nil
+        else
+          json
+        end
+      end
+
+      # Get exit code based on error severity.
+      #
+      # Useful for CI/CD pipelines.
+      #
+      # @param max_errors [Integer] Maximum errors allowed (default: 0)
+      # @return [Integer] Exit code (0 = success, 1 = errors found)
+      def exit_code(max_errors: 0)
+        return 0 if @navigation.errors.size <= max_errors
+
+        1
+      end
+
+      # Get report summary as hash.
+      #
+      # @return [Hash] Report summary
+      def summary
+        @navigation.statistics.merge(
+          document: {
+            name: @document.name,
+            format: @document.format,
+            language: @document.language_code
+          },
+          has_errors: @navigation.errors.any?
+        )
+      end
+
+      # Print report to stdout.
+      #
+      # @param format [Symbol] Output format (:text, :json, :yaml)
+      def print(format: :text)
+        case format
+        when :text
+          puts to_text
+        when :json
+          puts to_json
+        when :yaml
+          puts to_yaml
+        else
+          raise ArgumentError, "Unknown format: #{format}"
+        end
+      end
+
+      private
+
+      # Generate report data hash.
+      #
+      # @return [Hash] Report data
+      def generate_report_data
+        {
+          metadata: {
+            tool: "Kotoshu",
+            version: Kotoshu::VERSION,
+            generated_at: Time.now.utc.iso8601
+          },
+          document: {
+            name: @document.name,
+            format: @document.format.to_s,
+            language: @document.language_code,
+            word_count: @document.word_count,
+            line_count: @document.line_count
+          },
+          statistics: @navigation.statistics,
+          errors: @navigation.errors.map do |error|
+            {
+              id: error.id,
+              location: {
+                line: error.location.line,
+                column: error.location.column,
+                node_path: error.location.node_path
+              },
+              original: error.original,
+              suggestions: error.suggestions&.map do |sugg|
+                {
+                  word: sugg.word,
+                  confidence: sugg.confidence,
+                  source: sugg.source
+                }
+              end,
+              error_type: error.error_type.to_s,
+              confidence: error.confidence,
+              recommended_suggestion: error.recommended_suggestion&.word
+            }
+          end,
+          corrections: @navigation.export_corrections
+        }
+      end
+    end
+  end
+end