docsmith 0.1.0

data/lib/docsmith/comments/anchor.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module Docsmith
+  module Comments
+    # Builds and migrates range anchors for inline comments.
+    # An anchor captures character offsets and a content hash of the selected text
+    # so the comment can be relocated when content changes between versions.
+    module Anchor
+      ACTIVE   = "active"
+      DRIFTED  = "drifted"
+      ORPHANED = "orphaned"
+
+      # Builds anchor_data for a new range comment.
+      #
+      # @param content [String] the version content at comment time
+      # @param start_offset [Integer] character offset of selection start (inclusive)
+      # @param end_offset [Integer] character offset of selection end (exclusive)
+      # @return [Hash] anchor_data hash ready to store on the Comment
+      def self.build(content, start_offset:, end_offset:)
+        anchored_text = content[start_offset...end_offset].to_s
+        {
+          start_offset:  start_offset,
+          end_offset:    end_offset,
+          content_hash:  Digest::SHA256.hexdigest(anchored_text),
+          anchored_text: anchored_text,
+          status:        ACTIVE
+        }
+      end
+
+      # Attempts to migrate an existing anchor to new version content.
+      #
+      # Strategy:
+      # 1. Try exact offset — if SHA256 of text at same offsets matches, return ACTIVE.
+      # 2. Search the full content for the original anchored text — return DRIFTED with new offsets.
+      # 3. If not found anywhere, return ORPHANED.
+      #
+      # @param content [String] new version content
+      # @param anchor_data [Hash] existing anchor_data (string keys from JSON storage)
+      # @return [Hash] updated anchor_data with new :status
+      def self.migrate(content, anchor_data)
+        start_off     = anchor_data["start_offset"]
+        end_off       = anchor_data["end_offset"]
+        original_hash = anchor_data["content_hash"]
+        original_text = anchor_data["anchored_text"]
+
+        # 1. Exact offset check
+        candidate = content[start_off...end_off].to_s
+        return anchor_data.merge("status" => ACTIVE) if Digest::SHA256.hexdigest(candidate) == original_hash
+
+        # 2. Full-text search for relocated text
+        idx = content.index(original_text)
+        if idx
+          new_end = idx + original_text.length
+          return anchor_data.merge(
+            "start_offset" => idx,
+            "end_offset"   => new_end,
+            "status"       => DRIFTED
+          )
+        end
+
+        # 3. Orphaned — text no longer exists
+        anchor_data.merge("status" => ORPHANED)
+      end
+    end
+  end
+end

data/lib/docsmith/comments/comment.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Docsmith
+  module Comments
+    # Represents a comment on a specific DocumentVersion.
+    # Supports document-level and range-anchored inline annotations,
+    # threaded replies via parent/replies, and resolution tracking.
+    class Comment < ActiveRecord::Base
+      self.table_name = "docsmith_comments"
+
+      belongs_to :version,     class_name: "Docsmith::DocumentVersion", foreign_key: :version_id
+      belongs_to :author,      polymorphic: true, optional: true
+      belongs_to :parent,      class_name: "Docsmith::Comments::Comment", optional: true
+      belongs_to :resolved_by, polymorphic: true, optional: true
+      has_many   :replies,     class_name: "Docsmith::Comments::Comment",
+                               foreign_key: :parent_id, dependent: :destroy
+
+      validates :body,        presence: true
+      validates :anchor_type, inclusion: { in: %w[document range] }
+
+      scope :top_level,      -> { where(parent_id: nil) }
+      scope :unresolved,     -> { where(resolved: false) }
+      scope :document_level, -> { where(anchor_type: "document") }
+      scope :range_anchored, -> { where(anchor_type: "range") }
+
+      # Deserializes anchor_data from JSON text (SQLite) or returns hash directly (PostgreSQL jsonb).
+      #
+      # @return [Hash]
+      def anchor_data
+        raw = read_attribute(:anchor_data)
+        raw.is_a?(String) ? JSON.parse(raw) : raw.to_h
+      end
+
+      # Serializes anchor_data as JSON for storage.
+      #
+      # @param data [Hash, String]
+      def anchor_data=(data)
+        write_attribute(:anchor_data, data.is_a?(String) ? data : data.to_json)
+      end
+    end
+  end
+end

data/lib/docsmith/comments/manager.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Docsmith
+  module Comments
+    # Service object for creating and resolving comments on document versions.
+    class Manager
+      class << self
+        # Adds a comment to a specific version of a document.
+        #
+        # @param document [Docsmith::Document]
+        # @param version_number [Integer]
+        # @param body [String]
+        # @param author [Object] polymorphic author record
+        # @param anchor [Hash, nil] { start_offset:, end_offset: } for inline range comments
+        # @param parent [Comments::Comment, nil] parent comment for threading
+        # @return [Comments::Comment]
+        # @raise [ActiveRecord::RecordNotFound] if version_number does not exist
+        def add!(document, version_number:, body:, author:, anchor: nil, parent: nil)
+          version = Docsmith::DocumentVersion.find_by!(document: document, version_number: version_number)
+
+          anchor_type = anchor ? "range" : "document"
+          anchor_data = if anchor
+                          Anchor.build(version.content.to_s,
+                                       start_offset: anchor[:start_offset],
+                                       end_offset:   anchor[:end_offset])
+                        else
+                          {}
+                        end
+
+          comment = Comment.create!(
+            version:     version,
+            author:      author,
+            body:        body,
+            anchor_type: anchor_type,
+            anchor_data: anchor_data,
+            parent:      parent,
+            resolved:    false
+          )
+
+          Events::Notifier.instrument(:comment_added,
+            record:   document.subject || document,
+            document: document,
+            version:  version,
+            author:   author,
+            comment:  comment
+          )
+
+          comment
+        end
+
+        # Marks a comment as resolved.
+        #
+        # @param comment [Comments::Comment]
+        # @param by [Object] polymorphic resolver record
+        # @return [Comments::Comment]
+        def resolve!(comment, by:)
+          comment.update!(resolved: true, resolved_by: by, resolved_at: Time.current)
+
+          document = comment.version.document
+          Events::Notifier.instrument(:comment_resolved,
+            record:   document.subject || document,
+            document: document,
+            version:  comment.version,
+            author:   by,
+            comment:  comment
+          )
+
+          comment
+        end
+      end
+    end
+  end
+end

data/lib/docsmith/comments/migrator.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Docsmith
+  module Comments
+    # Migrates top-level comments from one version to another.
+    # Document-level comments are copied as-is.
+    # Range-anchored comments are re-anchored using Anchor.migrate;
+    # orphaned comments fire the :comment_orphaned event.
+    class Migrator
+      class << self
+        # @param document [Docsmith::Document]
+        # @param from [Integer] source version_number
+        # @param to [Integer] target version_number
+        # @return [void]
+        def migrate!(document, from:, to:)
+          from_version = Docsmith::DocumentVersion.find_by!(document: document, version_number: from)
+          to_version   = Docsmith::DocumentVersion.find_by!(document: document, version_number: to)
+          new_content  = to_version.content.to_s
+
+          from_version.comments.top_level.each do |comment|
+            new_anchor_data = migrate_anchor(comment, new_content)
+
+            new_comment = Comment.create!(
+              version:          to_version,
+              author_type:      comment.author_type,
+              author_id:        comment.author_id,
+              body:             comment.body,
+              anchor_type:      comment.anchor_type,
+              anchor_data:      new_anchor_data,
+              resolved:         comment.resolved,
+              resolved_by_type: comment.resolved_by_type,
+              resolved_by_id:   comment.resolved_by_id,
+              resolved_at:      comment.resolved_at
+            )
+
+            if orphaned?(comment, new_anchor_data)
+              Events::Notifier.instrument(:comment_orphaned,
+                record:   document.subject || document,
+                document: document,
+                version:  to_version,
+                author:   nil,
+                comment:  new_comment
+              )
+            end
+          end
+        end
+
+        private
+
+        # @return [Hash] migrated anchor_data
+        def migrate_anchor(comment, new_content)
+          return comment.anchor_data if comment.anchor_type == "document"
+
+          Anchor.migrate(new_content, comment.anchor_data)
+        end
+
+        # @return [Boolean]
+        def orphaned?(comment, new_anchor_data)
+          comment.anchor_type == "range" && new_anchor_data["status"] == Anchor::ORPHANED
+        end
+      end
+    end
+  end
+end

data/lib/docsmith/configuration.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Docsmith
+  # DSL object for per-class docsmith_config blocks.
+  # Each method call stores a key in @settings.
+  # Resolution against global config happens at read time via Configuration.resolve.
+  class ClassConfig
+    KEYS = %i[content_field content_type auto_save debounce max_versions content_extractor].freeze
+
+    # @return [Hash] raw settings set in this block
+    attr_reader :settings
+
+    def initialize
+      @settings = {}
+    end
+
+    KEYS.each do |key|
+      define_method(key) { |val| @settings[key] = val }
+    end
+  end
+
+  # Global configuration object. Set via Docsmith.configure { |c| ... }.
+  class Configuration
+    # Gem-level defaults — final fallback in resolution order.
+    # debounce stored as Integer (seconds); Duration values normalized via .to_i at resolve time.
+    DEFAULTS = {
+      content_field:     :body,
+      content_type:      :markdown,
+      auto_save:         true,
+      debounce:          30,
+      max_versions:      nil,
+      content_extractor: nil
+    }.freeze
+
+    # Maps ClassConfig keys to their global Configuration attribute names.
+    GLOBAL_KEY_MAP = {
+      content_field:     :default_content_field,
+      content_type:      :default_content_type,
+      auto_save:         :auto_save,
+      debounce:          :default_debounce,
+      max_versions:      :max_versions,
+      content_extractor: :content_extractor
+    }.freeze
+
+    attr_accessor :default_content_field, :default_content_type, :auto_save,
+                  :default_debounce, :max_versions, :content_extractor,
+                  :table_prefix, :diff_context_lines
+
+    def initialize
+      @default_content_field = DEFAULTS[:content_field]
+      @default_content_type  = DEFAULTS[:content_type]
+      @auto_save             = DEFAULTS[:auto_save]
+      @default_debounce      = DEFAULTS[:debounce]
+      @max_versions          = DEFAULTS[:max_versions]
+      @content_extractor     = DEFAULTS[:content_extractor]
+      @table_prefix          = "docsmith"
+      @diff_context_lines    = 3
+      @hooks                 = Hash.new { |h, k| h[k] = [] }
+    end
+
+    # Register a synchronous callback for a named event.
+    # @param event_name [Symbol] e.g. :version_created
+    # @yield [Docsmith::Events::Event]
+    def on(event_name, &block)
+      @hooks[event_name] << block
+    end
+
+    # @param event_name [Symbol]
+    # @return [Array<Proc>]
+    def hooks_for(event_name)
+      @hooks[event_name]
+    end
+
+    # Merge per-class settings over global config over gem defaults.
+    # Resolution is at read time — global changes after class definition still apply
+    # for keys the class does not override.
+    # @param class_settings [Hash]
+    # @param global_config [Docsmith::Configuration, nil]
+    # @return [Hash] fully resolved config
+    def self.resolve(class_settings, global_config)
+      DEFAULTS.each_with_object({}) do |(key, default_val), result|
+        global_key = GLOBAL_KEY_MAP[key]
+        global_val = global_config&.public_send(global_key)
+
+        result[key] = if class_settings.key?(key)
+                        class_settings[key]
+                      elsif !global_val.nil?
+                        global_val
+                      else
+                        default_val
+                      end
+      end.tap { |r| r[:debounce] = r[:debounce].to_i }
+    end
+  end
+end

data/lib/docsmith/diff/engine.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Docsmith
+  module Diff
+    # Computes diffs between two DocumentVersion records.
+    # For markdown and html content types, a format-aware parser is used
+    # (word-level for markdown, tag-atomic for html).
+    # Falls back to Renderers::Base (line-level) for json and unknown types.
+    class Engine
+      PARSERS = {
+        "markdown" => Parsers::Markdown,
+        "html"     => Parsers::Html
+      }.freeze
+
+      class << self
+        # @param version_a [Docsmith::DocumentVersion] the older version
+        # @param version_b [Docsmith::DocumentVersion] the newer version
+        # @return [Docsmith::Diff::Result]
+        def between(version_a, version_b)
+          content_type = version_a.content_type.to_s
+          parser       = PARSERS.fetch(content_type, Renderers::Base).new
+          changes      = parser.compute(version_a.content.to_s, version_b.content.to_s)
+
+          Result.new(
+            content_type: content_type,
+            from_version: version_a.version_number,
+            to_version:   version_b.version_number,
+            changes:      changes
+          )
+        end
+      end
+    end
+
+    # Convenience module method: Docsmith::Diff.between(v1, v2)
+    def self.between(version_a, version_b)
+      Engine.between(version_a, version_b)
+    end
+  end
+end

data/lib/docsmith/diff/parsers/html.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "diff/lcs"
+
+module Docsmith
+  module Diff
+    module Parsers
+      # HTML-aware diff parser for HTML documents.
+      #
+      # Tokenizes HTML so that each tag (including its attributes) is one atomic
+      # unit and text words are separate units. This prevents the diff engine from
+      # splitting `<p class="foo">` into angle brackets, attribute names, and values.
+      #
+      # Tokenization regex: /<[^>]+>|[^\s<>]+/
+      #   - /<[^>]+>/    matches any HTML tag: <p>, </p>, <div class="x">, <br/>
+      #   - /[^\s<>]+/   matches words in text content between tags
+      #
+      # Example: "<p>Hello world</p>" → ["<p>", "Hello", "world", "</p>"]
+      #
+      # The :line key in change hashes stores the 1-indexed token position
+      # (not a line number) for compatibility with Diff::Result serialization.
+      class Html < Renderers::Base
+        TAG_OR_WORD = /<[^>]+>|[^\s<>]+/.freeze
+
+        # @param old_content [String]
+        # @param new_content [String]
+        # @return [Array<Hash>] change hashes with :type, :line (token index), and content keys
+        def compute(old_content, new_content)
+          old_tokens = tokenize(old_content)
+          new_tokens = tokenize(new_content)
+          changes    = []
+
+          ::Diff::LCS.sdiff(old_tokens, new_tokens).each do |hunk|
+            case hunk.action
+            when "+"
+              changes << { type: :addition, line: hunk.new_position + 1, content: hunk.new_element.to_s }
+            when "-"
+              changes << { type: :deletion, line: hunk.old_position + 1, content: hunk.old_element.to_s }
+            when "!"
+              changes << {
+                type:        :modification,
+                line:        hunk.old_position + 1,
+                old_content: hunk.old_element.to_s,
+                new_content: hunk.new_element.to_s
+              }
+            end
+          end
+
+          changes
+        end
+
+        private
+
+        # Splits HTML into tokens:
+        # - Each HTML tag (including attributes) is one token
+        # - Each word in text content is one token
+        # Whitespace between tokens is discarded.
+        def tokenize(content)
+          content.scan(TAG_OR_WORD)
+        end
+      end
+    end
+  end
+end

data/lib/docsmith/diff/parsers/markdown.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+require "diff/lcs"
+
+module Docsmith
+  module Diff
+    module Parsers
+      # Word-level diff parser for Markdown documents.
+      #
+      # Instead of comparing line-by-line (as Renderers::Base does), this parser
+      # tokenizes content into individual words and newline groups, then diffs
+      # those tokens. This gives precise word-level change detection for prose,
+      # which is far more useful than "the whole line changed."
+      #
+      # Tokenization: content.scan(/\S+|\n+/)
+      #   "Hello world\n\nFoo" → ["Hello", "world", "\n\n", "Foo"]
+      #
+      # The :line key in change hashes stores the 1-indexed token position
+      # (not a line number) for compatibility with Diff::Result serialization.
+      class Markdown < Renderers::Base
+        # @param old_content [String]
+        # @param new_content [String]
+        # @return [Array<Hash>] change hashes with :type, :line (token index), and content keys
+        def compute(old_content, new_content)
+          old_tokens = tokenize(old_content)
+          new_tokens = tokenize(new_content)
+          changes    = []
+
+          ::Diff::LCS.sdiff(old_tokens, new_tokens).each do |hunk|
+            case hunk.action
+            when "+"
+              changes << { type: :addition, line: hunk.new_position + 1, content: hunk.new_element.to_s }
+            when "-"
+              changes << { type: :deletion, line: hunk.old_position + 1, content: hunk.old_element.to_s }
+            when "!"
+              changes << {
+                type:        :modification,
+                line:        hunk.old_position + 1,
+                old_content: hunk.old_element.to_s,
+                new_content: hunk.new_element.to_s
+              }
+            end
+          end
+
+          changes
+        end
+
+        private
+
+        # Splits markdown into word tokens.
+        # \S+ matches any non-whitespace run (words, punctuation, markdown markers).
+        # \n+ matches one or more consecutive newlines as a single token so that
+        # paragraph breaks (\n\n) and line breaks (\n) are each one diffable unit.
+        def tokenize(content)
+          content.scan(/\S+|\n+/)
+        end
+      end
+    end
+  end
+end

data/lib/docsmith/diff/renderers/base.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "diff/lcs"
+require "cgi"
+
+module Docsmith
+  module Diff
+    module Renderers
+      # Line-level diff renderer using diff-lcs.
+      # Handles all content types (markdown, html, json) for Phase 2.
+      # Register content-type-specific renderers via Renderers::Registry when needed.
+      class Base
+        # Computes line-level changes between two content strings.
+        #
+        # @param old_content [String]
+        # @param new_content [String]
+        # @return [Array<Hash>] change hashes with :type, :line, and content fields
+        def compute(old_content, new_content)
+          old_lines = old_content.split("\n", -1)
+          new_lines = new_content.split("\n", -1)
+          changes   = []
+
+          ::Diff::LCS.sdiff(old_lines, new_lines).each do |hunk|
+            case hunk.action
+            when "+"
+              changes << { type: :addition, line: hunk.new_position + 1, content: hunk.new_element.to_s }
+            when "-"
+              changes << { type: :deletion, line: hunk.old_position + 1, content: hunk.old_element.to_s }
+            when "!"
+              changes << {
+                type:        :modification,
+                line:        hunk.old_position + 1,
+                old_content: hunk.old_element.to_s,
+                new_content: hunk.new_element.to_s
+              }
+            end
+          end
+
+          changes
+        end
+
+        # Renders a change array as an HTML diff representation.
+        #
+        # @param changes [Array<Hash>]
+        # @return [String] HTML string
+        def render_html(changes)
+          lines = changes.map do |change|
+            case change[:type]
+            when :addition
+              %(<ins class="docsmith-addition">#{CGI.escapeHTML(change[:content])}</ins>)
+            when :deletion
+              %(<del class="docsmith-deletion">#{CGI.escapeHTML(change[:content])}</del>)
+            when :modification
+              %(<del class="docsmith-deletion">#{CGI.escapeHTML(change[:old_content])}</del><ins class="docsmith-addition">#{CGI.escapeHTML(change[:new_content])}</ins>)
+            end
+          end
+          %(<div class="docsmith-diff">#{lines.join("\n")}</div>)
+        end
+      end
+    end
+  end
+end

data/lib/docsmith/diff/renderers/registry.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Docsmith
+  module Diff
+    module Renderers
+      # Registry for diff renderers keyed by content type string.
+      # Falls back to Base for unregistered types.
+      # Use Docsmith.configure { |c| c.register_diff_renderer(:html, MyRenderer) }
+      # to add custom renderers at runtime.
+      class Registry
+        @renderers = {}
+
+        class << self
+          # @param content_type [String, Symbol]
+          # @param renderer_class [Class]
+          # @return [void]
+          def register(content_type, renderer_class)
+            @renderers[content_type.to_s] = renderer_class
+          end
+
+          # @param content_type [String, Symbol]
+          # @return [Class] renderer class; defaults to Base for unregistered types
+          def for(content_type)
+            @renderers.fetch(content_type.to_s, Base)
+          end
+
+          # @return [Hash] copy of registered renderers
+          def all
+            @renderers.dup
+          end
+
+          # Resets registry to empty — for test isolation only.
+          # @return [void]
+          def reset!
+            @renderers = {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/docsmith/diff/renderers.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative "renderers/base"
+
+module Docsmith
+  module Diff
+    module Renderers
+    end
+  end
+end