kotoshu 0.3.0

data/lib/kotoshu/documents/location.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Kotoshu
+  module Documents
+    # Unified location reference for errors in documents.
+    #
+    # Supports both line/column locations (plain text) and node paths
+    # (structured formats like Markdown, AsciiDoc).
+    #
+    # @example Plain text location
+    #   Location.new(line: 5, column: 12)
+    #
+    # @example Node path location
+    #   Location.new(node_path: [:paragraph, 3, :text, 2])
+    #
+    # @example Mixed location
+    #   Location.new(line: 5, column: 12, node_path: [:paragraph, 3])
+    class Location
+      attr_reader :line, :column, :node_path, :offset
+
+      # Create a new location.
+      #
+      # @param line [Integer, nil] Line number (1-indexed)
+      # @param column [Integer, nil] Column number (0-indexed)
+      # @param node_path [Array<Symbol, Integer>, nil] Path to node in AST
+      # @param offset [Integer, nil] Byte offset in content
+      def initialize(line: nil, column: nil, node_path: nil, offset: nil)
+        @line = line
+        @column = column
+        @node_path = node_path&.freeze
+        @offset = offset
+        freeze
+      end
+
+      # Check if this is a line/column location.
+      #
+      # @return [Boolean] True if has line and column
+      def line_column?
+        !@line.nil? && !@column.nil?
+      end
+
+      # Check if this is a node path location.
+      #
+      # @return [Boolean] True if has node path
+      def node_location?
+        !@node_path.nil? && !@node_path.empty?
+      end
+
+      # Comparison for sorting (by line, then column).
+      #
+      # @param other [Location] Another location
+      # @return [Integer] Comparison result (-1, 0, 1)
+      def <=>(other)
+        return 0 unless other.is_a?(Location)
+
+        if line_column? && other.line_column?
+          # Both line/column - sort by line then column
+          [@line, @column] <=> [other.line, other.column]
+        elsif line_column?
+          # We're line/column, other is node path - we come first
+          -1
+        elsif other.line_column?
+          # Other is line/column, we're node path - other comes first
+          1
+        else
+          # Both node paths - compare lexicographically
+          @node_path <=> other.node_path
+        end
+      end
+
+      # Check if this equals another location.
+      #
+      # @param other [Object] Another object
+      # @return [Boolean] True if locations match
+      def ==(other)
+        return false unless other.is_a?(Location)
+
+        @line == other.line &&
+          @column == other.column &&
+          @node_path == other.node_path &&
+          @offset == other.offset
+      end
+      alias_method :eql?, :==
+
+      # Hash code for hash table usage.
+      #
+      # @return [Integer] Hash code
+      def hash
+        [@line, @column, @node_path, @offset].hash
+      end
+
+      # String representation.
+      #
+      # @return [String] Human-readable representation
+      def to_s
+        if line_column?
+          "Line #{@line}:#{@column}"
+        elsif node_location?
+          "Path: #{@node_path.join('.')}"
+        elsif @offset
+          "Offset #{@offset}"
+        else
+          "Unknown"
+        end
+      end
+      alias_method :inspect, :to_s
+
+      # Create a location for a text node.
+      #
+      # @param node_path [Array] Path to the text node
+      # @param start_offset [Integer] Starting character offset
+      # @param length [Integer] Length of the text
+      # @return [Location] New location
+      def self.for_text_node(node_path, start_offset:, length:)
+        new(
+          node_path: node_path,
+          offset: start_offset
+        )
+      end
+
+      # Create a line/column location.
+      #
+      # @param line [Integer] Line number
+      # @param column [Integer] Column number
+      # @return [Location] New location
+      def self.for_line_column(line, column)
+        new(line: line, column: column)
+      end
+
+      # Create a line-only location.
+      #
+      # @param line [Integer] Line number
+      # @return [Location] New location
+      def self.for_line(line)
+        new(line: line, column: 0)
+      end
+    end
+  end
+end

data/lib/kotoshu/documents/markdown_document.rb

@@ -0,0 +1,389 @@
+# frozen_string_literal: true
+
+require_relative 'document'
+require_relative 'location'
+
+module Kotoshu
+  module Documents
+    # Markdown document implementation.
+    #
+    # Handles Markdown files with AST parsing for structured navigation.
+    #
+    # @example Creating a markdown document
+    #   doc = MarkdownDocument.new("# Title\n\nParagraph text")
+    #   doc.text_nodes.each { |node| puts node.text }
+    class MarkdownDocument < Document
+      require 'kramdown' if ENV['KOTOSHU_REQUIRE_MARKDOWN']
+
+      # Create a new markdown document.
+      #
+      # @param content [String] The document content
+      # @param format [Symbol] Document format (must be :markdown)
+      # @param language_code [String] Language code
+      def initialize(content, format: :markdown, language_code: 'en')
+        raise ArgumentError, "Format must be :markdown" unless format == :markdown
+
+        super(content, format: format, language_code: language_code)
+        @parsed = false
+        @ast = nil
+      end
+
+      # Parse the markdown document into an AST.
+      #
+      # @return [Hash] The parsed AST
+      def parse
+        return @ast if @parsed
+
+        begin
+          require 'kramdown'
+        rescue LoadError
+          raise "Kramdown gem not available. Add 'kramdown' to Gemfile"
+        end
+
+        kd = Kramdown::Document.new(content)
+        @ast = kd.to_hash
+        @parsed = true
+
+        @ast
+      end
+
+      # Get all text nodes for spell checking.
+      #
+      # Extracts text from the AST, skipping code blocks.
+      #
+      # @return [Array<TextNode>] Text nodes in the document
+      def text_nodes
+        extract_text_nodes
+      end
+
+      # Get node at a specific path in the AST.
+      #
+      # @param path [Array] Node path (e.g., [:document, :p, 1])
+      # @return [Object, nil] The node or nil
+      def get_node(path)
+        parse unless @parsed
+
+        navigate_ast(@ast, path)
+      end
+
+      # Get context around a location.
+      #
+      # For markdown, navigates the AST to find surrounding context.
+      #
+      # @param location [Location] The error location
+      # @param window [Integer] Number of sibling elements before/after
+      # @return [Models::Context] Context object
+      def context_for(location, window: 2)
+        return plain_text_context(location, window: 5) if location.line_column?
+
+        parse unless @parsed
+
+        # For node-based locations, find parent and siblings
+        parent_path = location.node_path[0..-2]
+        current_type = location.node_path.last
+
+        parent = navigate_ast(@ast, parent_path)
+        return Models::Context.new(before: "", current: "", after: "", location: location, window: window) unless parent
+
+        # Find siblings around current element
+        siblings = extract_siblings(parent)
+        current_idx = siblings.find_index { |s| s[:type] == current_type }
+
+        return Models::Context.new(before: "", current: "", after: "", location: location, window: window) unless current_idx
+
+        before_sibs = siblings[[0, current_idx - window].max..current_idx - 1]
+        after_sibs = siblings[(current_idx + 1)..(current_idx + window)]
+
+        before = before_sibs.map { |s| text_from_node(s) }.join("\n")
+        current = text_from_node(parent)
+        after = after_sibs.map { |s| text_from_node(s) }.join("\n")
+
+        Models::Context.new(
+          before: before,
+          current: current,
+          after: after,
+          location: location,
+          window: window
+        )
+      end
+
+      # Replace text at a specific location.
+      #
+      # Navigates the AST to find the text node and replaces it,
+      # then regenerates markdown.
+      #
+      # @param location [Location] The location to replace
+      # @param new_text [String] The new text
+      #return [MarkdownDocument] New document with replacement
+      def replace_node(location, new_text)
+        parse unless @parsed
+
+        # Navigate to the node and replace its text
+        modified_ast = replace_in_ast(@ast, location.node_path, new_text)
+
+        # Regenerate markdown from modified AST
+        begin
+          require 'kramdown'
+          new_content = Kramdown::Converter.new(modified_ast).to_kramdown
+        rescue LoadError
+          raise "Kramdown gem not available. Add 'kramdown' to Gemfile"
+        end
+
+        MarkdownDocument.new(new_content, @format, @language_code)
+      end
+
+      # Apply corrections and return new document.
+      #
+      # @param corrections [Array<Models::SemanticError>] Errors to fix
+      # @return [MarkdownDocument] New document with corrections
+      def apply(corrections)
+        return self if corrections.empty?
+
+        # Apply corrections one by one
+        result = self
+        corrections.each do |error|
+          suggestion = error.recommended_suggestion
+          result = result.replace_node(error.location, suggestion.word)
+        end
+
+        result
+      end
+
+      # Document name for display.
+      #
+      # @return [String] Document name
+      def name
+        "markdown"
+      end
+
+      private
+
+      # Extract text nodes from AST.
+      #
+      # @return [Array<TextNode>] Text nodes
+      def extract_text_nodes
+        parse unless @parsed
+        extract_from_ast(@ast)
+      end
+
+      # Extract text nodes recursively from AST.
+      #
+      # @param ast [Hash] The AST or node
+      # @param path [Array] Current path
+      # @return [Array<TextNode>] Text nodes
+      def extract_from_ast(ast, path: [])
+        nodes = []
+
+        case ast[:type]
+        when :text
+          nodes << TextNode.new(
+            ast[:value].strip,
+            location: Location.for_text_node(path, start_offset: 0, length: ast[:value].length),
+            node_path: path
+          )
+        when :p, :h1, :h2, :h3, :h4, :h5, :h6
+          # Check paragraph/header content
+          if ast[:value]
+            ast[:value].each_with_index do |child, idx|
+              nodes.concat(extract_from_ast(child, path + [:content, ast[:type], idx]))
+            end
+          end
+        when :blockquote
+          nodes.concat(extract_from_ast(ast[:value], path + [:blockquote]))
+        when :code_block
+          # Skip code blocks (don't check code)
+        when :link
+          # Check link text but not URL
+          link_text = ast[:value][:value]
+          if link_text && !link_text.empty?
+            nodes << TextNode.new(
+              link_text,
+              location: Location.for_text_node(path + [:link_text], start_offset: 0, length: link_text.length),
+              node_path: path + [:link_text]
+            )
+          end
+        when :strong, :em
+          # Check emphasis content
+          if ast[:value]
+            nodes.concat(extract_from_ast(ast[:value], path + [:emphasis]))
+          end
+        when :document
+          if ast[:children]
+            ast[:children].each_with_index do |child, idx|
+              nodes.concat(extract_from_ast(child, path + [:child, idx]))
+            end
+          end
+        when :list
+          # Check list items
+          if ast[:value]
+            ast[:value].each_with_index do |item, idx|
+              nodes.concat(extract_from_ast(item, path + [:item, idx]))
+            end
+          end
+        end
+
+        nodes
+      end
+
+      # Navigate AST to find node at path.
+      #
+      # @param ast [Hash] The AST
+      # @param path [Array] Node path
+      # @return [Object, nil] The node or nil
+      def navigate_ast(ast, path)
+        return nil unless path.is_a?(Array) || path.empty?
+
+        current = ast
+        path.each do |element|
+          case element
+          when Integer
+            # Array index
+            return nil unless current.is_a?(Array)
+            return nil if element >= current.size
+            current = current[element]
+          when Symbol, String
+            # Hash key
+            return nil unless current.is_a?(Hash)
+            current = current[element.to_sym]
+          else
+            return nil
+          end
+        end
+
+        current
+      end
+
+      # Extract sibling nodes from a parent node.
+      #
+      # @param parent [Hash] Parent node
+      # @return [Array<Hash>] Sibling nodes
+      def extract_siblings(parent)
+        case parent[:type]
+        when :document
+          parent[:children] || []
+        when :blockquote
+          [parent[:value]].compact
+        when :p, :h1, :h2, :h3, :h4, :h5, :h6
+          parent[:value] || []
+        when :list
+          parent[:value] || []
+        else
+          []
+        end
+      end
+
+      # Extract text content from a node.
+      #
+      # @param node [Hash] AST node
+      # @return [String] Text content
+      def text_from_node(node)
+        case node[:type]
+        when :text
+          node[:value]
+        when :p, :h1, :h2, :h3, :h4, :h5, :h6
+          # Extract text from inline elements
+          extract_inline_text(node[:value])
+        when :code_block
+          # Don't check code
+          nil
+        else
+          ""
+        end
+      end
+
+      # Extract text from inline markup.
+      #
+      # @param content [Array, String] Content with inline markup
+      # @return [String] Extracted text
+      def extract_inline_text(content)
+        return "" unless content
+
+        case content
+        when String
+          content
+        when Array
+          content.map { |elem| extract_inline_text(elem) }.join
+        when Hash
+          text = content[:value]
+          text ? extract_inline_text(text) : ""
+        else
+          ""
+        end
+      end
+
+      # Replace text in AST at a specific path.
+      #
+      # @param ast [Hash] The AST
+      # @param path [Array] Node path to the text node
+      # @param new_text [String] The replacement text
+      # @return [Hash] Modified AST (frozen)
+      def replace_in_ast(ast, path, new_text)
+        return ast if path.empty?
+
+        # Clone the AST (deep copy)
+        modified_ast = deep_clone_ast(ast)
+
+        # Navigate to the parent of the text node
+        current_path = path[0..-2]  # All but last element (the text node)
+        text_type = path.last  # Usually :text
+
+        current = navigate_ast(modified_ast, current_path)
+        return modified_ast unless current
+
+        if current.is_a?(Hash) && current[:type] == :text
+          # Replace the text value
+          current[:value] = new_text
+        elsif current.is_a?(Array)
+          # Array of elements - find text node and replace
+          current.each_with_index do |elem, idx|
+            if elem.is_a?(Hash) && elem[:type] == :text
+              current[idx][:value] = new_text
+              break
+            end
+          end
+        end
+
+        modified_ast
+      end
+
+      # Deep clone an AST.
+      #
+      # @param ast [Hash] The AST to clone
+      # @return [Hash] Cloned AST
+      def deep_clone_ast(ast)
+        case ast
+        when Hash
+          ast.transform_values { |v| deep_clone_ast(v) }
+        when Array
+          ast.map { |v| deep_clone_ast(v) }
+        else
+          ast
+        end
+      end
+
+      # Get plain text context for line/column locations.
+      #
+      # Fallback for line/column locations in structured documents.
+      #
+      # @param location [Location] The line/column location
+      # @param window [Integer] Number of lines before/after
+      # @return [Models::Context] Context object
+      def plain_text_context(location, window: 5)
+        start_line = [0, location.line - window - 1].max
+        end_line = [@lines.size - 1, location.line + window - 1].min
+
+        before = @lines[start_line...(location.line - 1)].join("\n")
+        current = @lines[location.line - 1]
+        after = @lines[(location.line + 1)..end_line].join("\n")
+
+        Models::Context.new(
+          before: before,
+          current: current,
+          after: after,
+          location: location,
+          window: window
+        )
+      end
+    end
+  end
+end

data/lib/kotoshu/documents/plain_text_document.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+require_relative 'document'
+require_relative '../models/context'
+
+module Kotoshu
+  module Documents
+    # Plain text document implementation.
+    #
+    # Handles plain text files with line-based navigation and correction.
+    #
+    # @example Creating a plain text document
+    #   doc = PlainTextDocument.new("Hello world\nHow are you?")
+    #   doc.text_nodes.each { |node| puts node.text }
+    class PlainTextDocument < Document
+      # Create a new plain text document.
+      #
+      # @param content [String] The document content
+      # @param format [Symbol] Document format (must be :text)
+      # @param language_code [String] Language code
+      def initialize(content, format: :text, language_code: 'en')
+        raise ArgumentError, "Format must be :text" unless format == :text
+
+        super(content, format: format, language_code: language_code)
+        @lines = content.lines
+      end
+
+      # Get all text nodes for spell checking.
+      #
+      # Each line becomes a text node.
+      #
+      # @return [Array<TextNode>] Text nodes (one per line)
+      def text_nodes
+        @lines.each_with_index.map do |line, idx|
+          # Strip leading/trailing whitespace but preserve structure
+          stripped_line = line.rstrip
+          next TextNode.new(
+            stripped_line,
+            location: Location.for_line_column(idx + 1, 0),
+            node_path: [:line, idx]
+          ) if stripped_line && !stripped_line.empty?
+        end.compact
+      end
+
+      # Get context around a location.
+      #
+      # Returns lines before and after the error location.
+      #
+      # @param location [Location] The error location (must be line/column)
+      # @param window [Integer] Number of lines before/after (default: 5)
+      # @return [Models::Context] Context object
+      def context_for(location, window: 5)
+        raise ArgumentError, "Location must be line/column" unless location.line_column?
+
+        start_line = [0, location.line - window - 1].max
+        end_line = [@lines.size - 1, location.line + window - 1].min
+
+        before = @lines[start_line...(location.line - 1)].join("\n")
+        current = @lines[location.line - 1]
+        after = @lines[(location.line + 1)..end_line].join("\n")
+
+        Models::Context.new(
+          before: before,
+          current: current,
+          after: after,
+          location: location,
+          window: window
+        )
+      end
+
+      # Get node at path (for plain text, just returns line).
+      #
+      # @param path [Array] Node path (e.g., [:line, 5])
+      # @return [String, nil] The line content
+      def get_node(path)
+        return nil unless path.is_a?(Array) && path.first == :line
+
+        line_idx = path[1]
+        return nil if line_idx < 0 || line_idx >= @lines.size
+
+        @lines[line_idx]
+      end
+
+      # Replace text at a specific location.
+      #
+      # For plain text, modifies a specific line.
+      #
+      # @param location [Location] The location to replace
+      # @param new_text [String] The new text
+      # @return [PlainTextDocument] New document with replacement
+      def replace_node(location, new_text)
+        raise ArgumentError, "Location must be line/column" unless location.line_column?
+
+        new_lines = @lines.dup
+        line = new_lines[location.line - 1]
+
+        # Replace the word at the specified column
+        if location.column > 0 && location.column < line.length
+          before = line[0...location.column]
+          after = line[(location.column + @original.length)..-1] || ''
+          line = "#{before}#{new_text}#{after}"
+        else
+          line = new_text
+        end
+
+        new_lines[location.line - 1] = line
+
+        PlainTextDocument.new(new_lines.join("\n"), @format, @language_code)
+      end
+
+      # Apply corrections and return new document.
+      #
+      # Corrections are applied in reverse order to preserve offsets.
+      #
+      # @param corrections [Array<Models::SemanticError>] Errors to fix
+      # @return [PlainTextDocument] New document with corrections
+      def apply(corrections)
+        return self if corrections.empty?
+
+        # Sort by location (reverse order for offset preservation)
+        sorted_corrections = corrections.sort_by { |c| c.location.line }.reverse
+
+        new_doc = self
+        corrections.each do |error|
+          suggestion = error.recommended_suggestion
+          new_doc = new_doc.replace_node(error.location, suggestion.word)
+        end
+
+        new_doc
+      end
+
+      # Document name for display.
+      #
+      # @return [String] Document name
+      def name
+        "plain_text"
+      end
+
+      # Get lines as array.
+      #
+      # @return [Array<String>] Lines
+      def lines
+        @lines
+      end
+    end
+  end
+end