docsmith 0.1.0

data/lib/docsmith/diff/result.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Docsmith
+  module Diff
+    # Holds the computed diff between two DocumentVersion records.
+    # Produced by Diff::Engine.between; consumed by callers for stats and rendering.
+    class Result
+      # @return [String] content type of the diffed document ("markdown", "html", "json")
+      attr_reader :content_type
+      # @return [Integer] version_number of the from (older) version
+      attr_reader :from_version
+      # @return [Integer] version_number of the to (newer) version
+      attr_reader :to_version
+      # @return [Array<Hash>] change hashes produced by Renderers::Base#compute
+      attr_reader :changes
+
+      # @param content_type [String]
+      # @param from_version [Integer]
+      # @param to_version [Integer]
+      # @param changes [Array<Hash>]
+      def initialize(content_type:, from_version:, to_version:, changes:)
+        @content_type = content_type
+        @from_version = from_version
+        @to_version   = to_version
+        @changes      = changes
+      end
+
+      # @return [Integer] number of added lines
+      def additions
+        changes.count { |c| c[:type] == :addition }
+      end
+
+      # @return [Integer] number of deleted lines
+      def deletions
+        changes.count { |c| c[:type] == :deletion }
+      end
+
+      # @return [String] HTML diff representation
+      def to_html
+        Renderers::Registry.for(content_type).new.render_html(changes)
+      end
+
+      # @return [String] JSON diff representation matching the documented schema
+      def to_json(*)
+        {
+          content_type: content_type,
+          from_version: from_version,
+          to_version:   to_version,
+          stats:        { additions: additions, deletions: deletions },
+          changes:      changes.map { |c| serialize_change(c) }
+        }.to_json
+      end
+
+      private
+
+      def serialize_change(change)
+        case change[:type]
+        when :addition
+          { type: "addition", position: { line: change[:line] }, content: change[:content] }
+        when :deletion
+          { type: "deletion", position: { line: change[:line] }, content: change[:content] }
+        when :modification
+          {
+            type:        "modification",
+            position:    { line: change[:line] },
+            old_content: change[:old_content],
+            new_content: change[:new_content]
+          }
+        else
+          change.transform_keys(&:to_s)
+        end
+      end
+    end
+  end
+end

data/lib/docsmith/diff.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Docsmith
+  module Diff
+  end
+end

data/lib/docsmith/document.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Docsmith
+  # AR model backed by docsmith_documents.
+  # Serves as both a standalone versioned document and the shadow record
+  # auto-created when Docsmith::Versionable is included on any AR model.
+  #
+  # Shadow record lifecycle:
+  #   include Docsmith::Versionable on Article → first save_version! call does:
+  #     Docsmith::Document.find_or_create_by!(subject: article_instance)
+  #   subject_type / subject_id link back to the originating record.
+  class Document < ActiveRecord::Base
+    self.table_name = "docsmith_documents"
+
+    belongs_to :subject, polymorphic: true, optional: true
+    has_many :document_versions,
+             -> { order(:version_number) },
+             foreign_key: :document_id,
+             class_name:  "Docsmith::DocumentVersion",
+             dependent:   :destroy
+    has_many :version_tags,
+             through:    :document_versions,
+             class_name: "Docsmith::VersionTag"
+
+    validates :content_type, presence: true,
+              inclusion: { in: %w[html markdown json] }
+
+    # @return [Docsmith::DocumentVersion, nil] latest version by version_number
+    def current_version
+      document_versions.last
+    end
+
+    # Find or create the shadow Document for an existing AR record.
+    # @param record [ActiveRecord::Base]
+    # @param field [Symbol, nil] ignored — content_field comes from class config
+    # @return [Docsmith::Document]
+    def self.from_record(record, field: nil)
+      find_or_create_by!(subject: record) do |doc|
+        doc.content_type = "markdown"
+        doc.title = record.respond_to?(:title) ? record.title.to_s : record.class.name
+      end
+    end
+  end
+end

data/lib/docsmith/document_version.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Docsmith
+  # Immutable content snapshot. Table is docsmith_versions.
+  # Class name is DocumentVersion (not Version) to avoid colliding with
+  # lib/docsmith/version.rb which holds the Docsmith::VERSION constant.
+  class DocumentVersion < ActiveRecord::Base
+    self.table_name = "docsmith_versions"
+
+    belongs_to :document,
+               class_name:  "Docsmith::Document",
+               foreign_key: :document_id
+    belongs_to :author, polymorphic: true, optional: true
+    has_many   :version_tags,
+               class_name:  "Docsmith::VersionTag",
+               foreign_key: :version_id,
+               dependent:   :destroy
+    has_many :comments,
+             class_name:  "Docsmith::Comments::Comment",
+             foreign_key: :version_id,
+             dependent:   :destroy
+
+    validates :version_number, presence: true,
+              uniqueness: { scope: :document_id }
+    validates :content,      presence: true
+    validates :content_type, presence: true,
+              inclusion: { in: %w[html markdown json] }
+
+    # @return [Docsmith::DocumentVersion, nil]
+    def previous_version
+      document.document_versions
+              .where("version_number < ?", version_number)
+              .last
+    end
+
+    # Renders this version's content in the given output format.
+    #
+    # @param format [Symbol] :html or :json
+    # @param options [Hash] passed through to the renderer
+    # @return [String]
+    # @raise [ArgumentError] for unknown formats
+    def render(format, **options)
+      case format.to_sym
+      when :html then Rendering::HtmlRenderer.new.render(self, **options)
+      when :json then Rendering::JsonRenderer.new.render(self, **options)
+      else raise ArgumentError, "Unknown render format: #{format}. Supported: :html, :json"
+      end
+    end
+  end
+end

data/lib/docsmith/errors.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module Docsmith
+  # Base class for all Docsmith errors.
+  class Error < StandardError; end
+
+  # Raised when content_field returns a non-String and no content_extractor is configured.
+  class InvalidContentField < Error; end
+
+  # Raised when max_versions is set, all versions are tagged, and a new version would exceed the limit.
+  class MaxVersionsExceeded < Error; end
+
+  # Raised when a requested version_number does not exist on the document.
+  class VersionNotFound < Error; end
+
+  # Raised when tag_version! is called with a name already used on this document.
+  class TagAlreadyExists < Error; end
+end

data/lib/docsmith/events/event.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Docsmith
+  module Events
+    # Immutable payload for all Docsmith events.
+    # Fields on every event: record, document, version, author.
+    # Extra fields by event:
+    #   version_restored → from_version
+    #   version_tagged   → tag_name
+    #   comment_added/orphaned → comment  (Phase 3)
+    #   branch_created/merged  → branch   (Phase 4)
+    Event = Struct.new(
+      :record, :document, :version, :author,
+      :from_version, :tag_name,
+      :comment, :branch, :conflicts, :merge_result,
+      keyword_init: true
+    )
+  end
+end

data/lib/docsmith/events/hook_registry.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Docsmith
+  module Events
+    # Calls synchronous hooks registered via Docsmith.configure { |c| c.on(:event) { } }.
+    module HookRegistry
+      # @param event_name [Symbol]
+      # @param event [Docsmith::Events::Event]
+      def self.call(event_name, event)
+        Docsmith.configuration.hooks_for(event_name).each { |hook| hook.call(event) }
+      end
+    end
+  end
+end

data/lib/docsmith/events/notifier.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "active_support/notifications"
+
+module Docsmith
+  module Events
+    # Fires both AS::Notifications and callback hooks for every action.
+    # Instrument name format: "#{event_name}.docsmith" (e.g. "version_created.docsmith").
+    module Notifier
+      # @param event_name [Symbol]
+      # @param payload [Hash] keyword args forwarded to Event.new
+      # @return [Docsmith::Events::Event]
+      def self.instrument(event_name, **payload)
+        event = Event.new(**payload)
+        ActiveSupport::Notifications.instrument("#{event_name}.docsmith", payload) do
+          HookRegistry.call(event_name, event)
+        end
+        event
+      end
+    end
+  end
+end

data/lib/docsmith/rendering/html_renderer.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "json"
+
+module Docsmith
+  module Rendering
+    # Renders a DocumentVersion's content as an HTML string.
+    # Markdown is shown pre-formatted (no external gem dependency).
+    # JSON is pretty-printed inside a pre block.
+    # Subclass and override #render to plug in a markdown gem (e.g. redcarpet).
+    class HtmlRenderer
+      # @param version [Docsmith::DocumentVersion]
+      # @param options [Hash] unused in Phase 2; available for subclasses
+      # @return [String] HTML representation of the version content
+      def render(version, **options)
+        content      = version.content.to_s
+        content_type = version.content_type.to_s
+
+        case content_type
+        when "html"
+          content
+        when "markdown"
+          "<pre class=\"docsmith-markdown\">#{CGI.escapeHTML(content)}</pre>"
+        when "json"
+          pretty = JSON.pretty_generate(JSON.parse(content))
+          "<pre class=\"docsmith-json\">#{CGI.escapeHTML(pretty)}</pre>"
+        else
+          "<pre>#{CGI.escapeHTML(content)}</pre>"
+        end
+      rescue JSON::ParserError
+        "<pre>#{CGI.escapeHTML(content)}</pre>"
+      end
+    end
+  end
+end

data/lib/docsmith/rendering/json_renderer.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Docsmith
+  module Rendering
+    # Renders a DocumentVersion's content as a JSON string.
+    # For json content_type: re-parses and pretty-prints.
+    # For other types: wraps content in a JSON envelope.
+    class JsonRenderer
+      # @param version [Docsmith::DocumentVersion]
+      # @param options [Hash] unused in Phase 2
+      # @return [String] JSON representation of the version content
+      def render(version, **options)
+        content      = version.content.to_s
+        content_type = version.content_type.to_s
+
+        case content_type
+        when "json"
+          JSON.pretty_generate(JSON.parse(content))
+        else
+          { content_type: content_type, content: content }.to_json
+        end
+      rescue JSON::ParserError
+        { content_type: content_type, content: content, error: "invalid_json" }.to_json
+      end
+    end
+  end
+end

data/lib/docsmith/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Docsmith
+  VERSION = "0.1.0"
+end

data/lib/docsmith/version_manager.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Docsmith
+  # Service object for all version lifecycle operations.
+  # The Versionable mixin delegates here after resolving the shadow document.
+  # Always receives a Docsmith::Document instance.
+  module VersionManager
+    # Create a new DocumentVersion snapshot.
+    # Returns nil if content is identical to the latest version (string == check).
+    #
+    # @param document [Docsmith::Document]
+    # @param author [Object, nil]
+    # @param summary [String, nil]
+    # @param config [Hash] resolved config
+    # @return [Docsmith::DocumentVersion, nil]
+    def self.save!(document, author:, summary: nil, config: nil)
+      config  ||= Configuration.resolve({}, Docsmith.configuration)
+      current   = document.content.to_s
+      latest    = document.document_versions.last
+
+      return nil if latest && latest.content == current
+
+      next_num = document.versions_count + 1
+
+      version = DocumentVersion.create!(
+        document:       document,
+        version_number: next_num,
+        content:        current,
+        content_type:   document.content_type,
+        author:         author,
+        change_summary: summary,
+        metadata:       {}
+      )
+
+      document.update_columns(
+        versions_count:    next_num,
+        last_versioned_at: Time.current
+      )
+      document.versions_count = next_num
+
+      prune_if_needed!(document, version, config) if config[:max_versions]
+
+      record = document.subject || document
+      Events::Notifier.instrument(:version_created,
+        record: record, document: document, version: version, author: author)
+
+      version
+    end
+
+    # Restore a previous version by creating a new version with its content.
+    # Fires :version_restored (not :version_created). Never mutates existing versions.
+    #
+    # @param document [Docsmith::Document]
+    # @param version [Integer] version_number to restore from
+    # @param author [Object, nil]
+    # @param config [Hash] resolved config
+    # @return [Docsmith::DocumentVersion] the new version
+    # @raise [Docsmith::VersionNotFound]
+    def self.restore!(document, version:, author:, config: nil)
+      config      ||= Configuration.resolve({}, Docsmith.configuration)
+      from_version  = document.document_versions.find_by(version_number: version)
+      raise VersionNotFound, "Version #{version} not found on this document" unless from_version
+
+      next_num = document.versions_count + 1
+
+      new_version = DocumentVersion.create!(
+        document:       document,
+        version_number: next_num,
+        content:        from_version.content,
+        content_type:   document.content_type,
+        author:         author,
+        change_summary: "Restored from v#{version}",
+        metadata:       {}
+      )
+
+      document.update_columns(
+        content:           from_version.content,
+        versions_count:    next_num,
+        last_versioned_at: Time.current
+      )
+
+      record = document.subject || document
+      Events::Notifier.instrument(:version_restored,
+        record: record, document: document, version: new_version,
+        author: author, from_version: from_version)
+
+      new_version
+    end
+
+    # Tag a specific version with a name unique to this document.
+    #
+    # @param document [Docsmith::Document]
+    # @param version [Integer] version_number to tag
+    # @param name [String] unique per document
+    # @param author [Object, nil]
+    # @return [Docsmith::VersionTag]
+    # @raise [Docsmith::VersionNotFound]
+    # @raise [Docsmith::TagAlreadyExists]
+    def self.tag!(document, version:, name:, author:)
+      version_record = document.document_versions.find_by(version_number: version)
+      raise VersionNotFound, "Version #{version} not found on this document" unless version_record
+
+      if VersionTag.exists?(document_id: document.id, name: name)
+        raise TagAlreadyExists, "Tag '#{name}' already exists on this document"
+      end
+
+      tag = VersionTag.create!(
+        document: document,
+        version:  version_record,
+        name:     name,
+        author:   author
+      )
+
+      record = document.subject || document
+      Events::Notifier.instrument(:version_tagged,
+        record: record, document: document, version: version_record,
+        author: author, tag_name: name)
+
+      tag
+    end
+
+    def self.prune_if_needed!(document, new_version, config)
+      max = config[:max_versions]
+      return unless max && document.versions_count > max
+
+      tagged_ids      = VersionTag.where(document_id: document.id).select(:version_id)
+      oldest_untagged = document.document_versions
+                                .where.not(id: tagged_ids)
+                                .where.not(id: new_version.id)
+                                .first
+
+      unless oldest_untagged
+        raise MaxVersionsExceeded,
+          "All #{document.versions_count} versions are tagged. Cannot prune to stay within " \
+          "max_versions: #{max}. Remove a tag or increase max_versions."
+      end
+
+      oldest_untagged.destroy!
+      document.update_column(:versions_count, document.versions_count - 1)
+    end
+    private_class_method :prune_if_needed!
+  end
+end

data/lib/docsmith/version_tag.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Docsmith
+  # Named label on a DocumentVersion.
+  # Tag names are unique per document (not per version) — enforced at DB level
+  # via the unique index on [document_id, name] in docsmith_version_tags.
+  # document_id is denormalized on this table to enable that DB-level constraint.
+  class VersionTag < ActiveRecord::Base
+    self.table_name = "docsmith_version_tags"
+
+    belongs_to :document,
+               class_name:  "Docsmith::Document",
+               foreign_key: :document_id
+    belongs_to :version,
+               class_name:  "Docsmith::DocumentVersion",
+               foreign_key: :version_id
+    belongs_to :author, polymorphic: true, optional: true
+
+    validates :name,        presence: true
+    validates :document_id, presence: true
+    validates :version_id,  presence: true
+    validates :name, uniqueness: { scope: :document_id,
+                                   message: "already exists on this document" }
+  end
+end