docsmith 0.1.0

data/lib/docsmith/versionable.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+module Docsmith
+  # ActiveRecord mixin that adds full versioning to any model.
+  #
+  # Usage:
+  #   class Article < ApplicationRecord
+  #     include Docsmith::Versionable
+  #     docsmith_config { content_field :body; content_type :markdown }
+  #   end
+  module Versionable
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.after_save(:_docsmith_auto_save_callback)
+    end
+
+    module ClassMethods
+      # Configure per-class Docsmith options. All keys optional.
+      # Unset keys fall through to global config then gem defaults.
+      # @yield block evaluated on a Docsmith::ClassConfig instance
+      # @return [Docsmith::ClassConfig]
+      def docsmith_config(&block)
+        @_docsmith_class_config ||= Docsmith::ClassConfig.new
+        @_docsmith_class_config.instance_eval(&block) if block_given?
+        @_docsmith_class_config
+      end
+
+      # @return [Hash] fully resolved config (read-time resolution)
+      def docsmith_resolved_config
+        Docsmith::Configuration.resolve(
+          @_docsmith_class_config&.settings || {},
+          Docsmith.configuration
+        )
+      end
+    end
+
+    # Create a new DocumentVersion snapshot of this record's content.
+    # Returns nil if content is identical to the latest version.
+    # Raises Docsmith::InvalidContentField if content_field returns a non-String
+    # and no content_extractor is configured.
+    #
+    # @param author [Object, nil]
+    # @param summary [String, nil]
+    # @return [Docsmith::DocumentVersion, nil]
+    def save_version!(author:, summary: nil)
+      _sync_docsmith_content!
+      Docsmith::VersionManager.save!(
+        _docsmith_document,
+        author:  author,
+        summary: summary,
+        config:  self.class.docsmith_resolved_config
+      )
+    end
+
+    # Debounced auto-save. Returns nil if debounce window has not elapsed
+    # OR content is unchanged. Both non-save cases return nil.
+    # auto_save: false in config causes this to always return nil.
+    #
+    # @param author [Object, nil]
+    # @return [Docsmith::DocumentVersion, nil]
+    def auto_save_version!(author: nil)
+      config = self.class.docsmith_resolved_config
+      return nil unless config[:auto_save]
+
+      _sync_docsmith_content!
+      Docsmith::AutoSave.call(_docsmith_document, author: author, config: config)
+    end
+
+    # @return [ActiveRecord::Relation<Docsmith::DocumentVersion>] ordered by version_number
+    def versions
+      _docsmith_document.document_versions
+    end
+
+    # @return [Docsmith::DocumentVersion, nil] latest version
+    def current_version
+      _docsmith_document.current_version
+    end
+
+    # @param number [Integer] 1-indexed version_number
+    # @return [Docsmith::DocumentVersion, nil]
+    def version(number)
+      _docsmith_document.document_versions.find_by(version_number: number)
+    end
+
+    # Restore to a previous version. Creates a new version with the old content.
+    # Syncs restored content back to the model's content_field via update_column
+    # (bypasses after_save to prevent a duplicate auto-save).
+    # Never mutates existing versions.
+    #
+    # @param number [Integer] version_number to restore from
+    # @param author [Object, nil]
+    # @return [Docsmith::DocumentVersion]
+    # @raise [Docsmith::VersionNotFound]
+    def restore_version!(number, author:)
+      result = Docsmith::VersionManager.restore!(
+        _docsmith_document,
+        version: number,
+        author:  author,
+        config:  self.class.docsmith_resolved_config
+      )
+      field = self.class.docsmith_resolved_config[:content_field]
+      update_column(field, _docsmith_document.reload.content)
+      result
+    end
+
+    # Tag a specific version. Names are unique per document.
+    # @param number [Integer] version_number to tag
+    # @param name [String]
+    # @param author [Object, nil]
+    # @return [Docsmith::VersionTag]
+    def tag_version!(number, name:, author:)
+      Docsmith::VersionManager.tag!(
+        _docsmith_document, version: number, name: name, author: author)
+    end
+
+    # @param tag_name [String]
+    # @return [Docsmith::DocumentVersion, nil]
+    def tagged_version(tag_name)
+      tag = _docsmith_document.version_tags.find_by(name: tag_name)
+      tag&.version
+    end
+
+    # @param number [Integer] version_number
+    # @return [Array<String>] tag names on that version
+    def version_tags(number)
+      ver = version(number)
+      return [] unless ver
+      ver.version_tags.pluck(:name)
+    end
+
+    # Computes a diff from version N to the current (latest) version.
+    #
+    # @param version_number [Integer]
+    # @return [Docsmith::Diff::Result]
+    # @raise [ActiveRecord::RecordNotFound] if version_number does not exist
+    def diff_from(version_number)
+      doc    = _docsmith_document
+      v_from = Docsmith::DocumentVersion.find_by!(document: doc, version_number: version_number)
+      v_to   = Docsmith::DocumentVersion.where(document_id: doc.id).order(version_number: :desc).first!
+      Docsmith::Diff.between(v_from, v_to)
+    end
+
+    # Computes a diff between two named versions.
+    #
+    # @param from_version [Integer]
+    # @param to_version [Integer]
+    # @return [Docsmith::Diff::Result]
+    # @raise [ActiveRecord::RecordNotFound] if either version does not exist
+    def diff_between(from_version, to_version)
+      doc    = _docsmith_document
+      v_from = Docsmith::DocumentVersion.find_by!(document: doc, version_number: from_version)
+      v_to   = Docsmith::DocumentVersion.find_by!(document: doc, version_number: to_version)
+      Docsmith::Diff.between(v_from, v_to)
+    end
+
+    # Adds a comment to a specific version of this document.
+    #
+    # @param version [Integer] version_number
+    # @param body [String]
+    # @param author [Object] polymorphic author
+    # @param anchor [Hash, nil] { start_offset:, end_offset: } for inline range comments
+    # @param parent [Comments::Comment, nil] parent comment for threading
+    # @return [Docsmith::Comments::Comment]
+    def add_comment!(version:, body:, author:, anchor: nil, parent: nil)
+      Comments::Manager.add!(
+        _docsmith_document,
+        version_number: version,
+        body:           body,
+        author:         author,
+        anchor:         anchor,
+        parent:         parent
+      )
+    end
+
+    # Returns all comments across all versions of this document.
+    #
+    # @return [ActiveRecord::Relation<Docsmith::Comments::Comment>]
+    def comments
+      doc = _docsmith_document
+      Comments::Comment.joins(:version)
+                       .where(docsmith_versions: { document_id: doc.id })
+    end
+
+    # Returns comments on a specific version, optionally filtered by anchor type.
+    #
+    # @param version [Integer] version_number
+    # @param type [Symbol, nil] :document or :range to filter; nil = all
+    # @return [ActiveRecord::Relation<Docsmith::Comments::Comment>]
+    def comments_on(version:, type: nil)
+      doc = _docsmith_document
+      dv  = Docsmith::DocumentVersion.find_by!(document: doc, version_number: version)
+      rel = Comments::Comment.where(version: dv)
+      rel = rel.where(anchor_type: type.to_s) if type
+      rel
+    end
+
+    # Returns all unresolved comments across all versions.
+    #
+    # @return [ActiveRecord::Relation<Docsmith::Comments::Comment>]
+    def unresolved_comments
+      comments.merge(Comments::Comment.unresolved)
+    end
+
+    # Migrates top-level comments from one version to another.
+    #
+    # @param from [Integer] source version_number
+    # @param to [Integer] target version_number
+    # @return [void]
+    def migrate_comments!(from:, to:)
+      Comments::Migrator.migrate!(_docsmith_document, from: from, to: to)
+    end
+
+    private
+
+    # Finds or creates the shadow Docsmith::Document for this record.
+    # Cached in @_docsmith_document after first lookup.
+    def _docsmith_document
+      config = self.class.docsmith_resolved_config
+      @_docsmith_document ||= Docsmith::Document.find_or_create_by!(subject: self) do |doc|
+        doc.content_type = config[:content_type].to_s
+        doc.title        = respond_to?(:title) ? title.to_s : self.class.name
+      end
+    end
+
+    # Reads content from the model via content_extractor or content_field,
+    # validates it is a String, then syncs to the shadow document's content column.
+    def _sync_docsmith_content!
+      config = self.class.docsmith_resolved_config
+
+      raw = if config[:content_extractor]
+              config[:content_extractor].call(self)
+            else
+              public_send(config[:content_field])
+            end
+
+      unless raw.nil? || raw.is_a?(String)
+        source = config[:content_extractor] ? "content_extractor" : "content_field :#{config[:content_field]}"
+        raise Docsmith::InvalidContentField,
+          "#{source} must return a String, got #{raw.class}. " \
+          "Use content_extractor: ->(record) { ... } for non-string fields."
+      end
+
+      _docsmith_document.update_column(:content, raw.to_s)
+    end
+
+    def _docsmith_auto_save_callback
+      auto_save_version!
+    rescue Docsmith::InvalidContentField
+      nil
+    end
+  end
+end

data/lib/docsmith.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_support"
+require "active_support/core_ext/numeric/time"
+require "active_support/notifications"
+
+require_relative "docsmith/version"
+require_relative "docsmith/errors"
+require_relative "docsmith/configuration"
+require_relative "docsmith/events/event"
+require_relative "docsmith/events/hook_registry"
+require_relative "docsmith/events/notifier"
+require_relative "docsmith/document"
+require_relative "docsmith/document_version"
+require_relative "docsmith/version_tag"
+require_relative "docsmith/auto_save"
+require_relative "docsmith/version_manager"
+require_relative "docsmith/versionable"
+require_relative "docsmith/diff"
+require_relative "docsmith/diff/renderers"
+require_relative "docsmith/diff/renderers/base"
+require_relative "docsmith/diff/renderers/registry"
+require_relative "docsmith/diff/result"
+require_relative "docsmith/diff/parsers/markdown"
+require_relative "docsmith/diff/parsers/html"
+require_relative "docsmith/diff/engine"
+require_relative "docsmith/rendering/html_renderer"
+require_relative "docsmith/rendering/json_renderer"
+require_relative "docsmith/comments/comment"
+require_relative "docsmith/comments/anchor"
+require_relative "docsmith/comments/manager"
+require_relative "docsmith/comments/migrator"
+
+module Docsmith
+  class << self
+    # @yield [Docsmith::Configuration]
+    def configure
+      yield configuration
+    end
+
+    # @return [Docsmith::Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Reset to gem defaults. Call in specs via config.before(:each).
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

data/lib/generators/docsmith/install/install_generator.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "rails/generators"
+require "rails/generators/active_record"
+
+module Docsmith
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include ActiveRecord::Generators::Migration
+
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Creates the Docsmith migration and initializer."
+
+      def create_migration
+        migration_template(
+          "create_docsmith_tables.rb.erb",
+          "db/migrate/create_docsmith_tables.rb"
+        )
+      end
+
+      def create_initializer
+        template "docsmith_initializer.rb.erb", "config/initializers/docsmith.rb"
+      end
+    end
+  end
+end

data/lib/generators/docsmith/install/templates/create_docsmith_tables.rb.erb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+class CreateDocsmithTables < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :docsmith_documents do |t|
+      t.string   :title
+      t.text     :content
+      t.string   :content_type,       null: false, default: "markdown"
+      t.integer  :versions_count,     null: false, default: 0
+      t.datetime :last_versioned_at
+      t.string   :subject_type
+      t.bigint   :subject_id
+      t.jsonb    :metadata,           null: false, default: {}
+      t.timestamps
+    end
+    add_index :docsmith_documents, %i[subject_type subject_id]
+
+    create_table :docsmith_versions do |t|
+      t.references :document,       null: false, foreign_key: { to_table: :docsmith_documents }
+      t.integer    :version_number, null: false
+      t.text       :content,        null: false
+      t.string     :content_type,   null: false
+      t.string     :author_type
+      t.bigint     :author_id
+      t.string     :change_summary
+      t.jsonb      :metadata,       null: false, default: {}
+      t.datetime   :created_at,     null: false
+    end
+    add_index :docsmith_versions, %i[document_id version_number], unique: true
+    add_index :docsmith_versions, %i[author_type author_id]
+
+    create_table :docsmith_version_tags do |t|
+      t.references :document,   null: false, foreign_key: { to_table: :docsmith_documents }
+      t.bigint     :version_id, null: false
+      t.string     :name,       null: false
+      t.string     :author_type
+      t.bigint     :author_id
+      t.datetime   :created_at, null: false
+    end
+    add_index :docsmith_version_tags, %i[document_id name], unique: true
+    add_index :docsmith_version_tags, [:version_id]
+    add_foreign_key :docsmith_version_tags, :docsmith_versions, column: :version_id
+
+    create_table :docsmith_comments do |t|
+      t.bigint   :version_id,        null: false
+      t.bigint   :parent_id
+      t.string   :author_type
+      t.bigint   :author_id
+      t.text     :body,              null: false
+      t.string   :anchor_type,       null: false, default: "document"
+      t.jsonb    :anchor_data,       null: false, default: {}
+      t.boolean  :resolved,          null: false, default: false
+      t.string   :resolved_by_type
+      t.bigint   :resolved_by_id
+      t.datetime :resolved_at
+      t.timestamps                   null: false
+    end
+    add_index :docsmith_comments, :version_id
+    add_index :docsmith_comments, :parent_id
+    add_index :docsmith_comments, [:author_type, :author_id]
+    add_foreign_key :docsmith_comments, :docsmith_versions, column: :version_id
+    add_foreign_key :docsmith_comments, :docsmith_comments, column: :parent_id
+  end
+end

data/lib/generators/docsmith/install/templates/docsmith_initializer.rb.erb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+Docsmith.configure do |config|
+  # Resolution order: per-class docsmith_config > this global config > gem defaults
+  #
+  # config.default_content_field    = :body          # gem default: :body
+  # config.default_content_type     = :markdown      # gem default: :markdown (:html, :markdown, :json)
+  # config.auto_save                = true           # gem default: true
+  # config.default_debounce         = 30             # gem default: 30 (integer seconds)
+  # config.max_versions             = nil            # gem default: nil (unlimited)
+  # config.content_extractor        = nil            # example: ->(record) { record.body.to_html }
+  # config.table_prefix             = "docsmith"     # gem default: "docsmith"
+  # config.diff_context_lines       = 3
+  #
+  # Event hooks (fires synchronously before AS::Notifications):
+  # config.on(:version_created)  { |event| Rails.logger.info "v#{event.version.version_number} saved" }
+  # config.on(:version_restored) { |event| }
+  # config.on(:version_tagged)   { |event| }
+end

data/sig/docsmith.rbs

@@ -0,0 +1,4 @@
+module Docsmith
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,196 @@
+--- !ruby/object:Gem::Specification
+name: docsmith
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- swastik009
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2026-04-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: diff-lcs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.4'
+- !ruby/object:Gem::Dependency
+  name: factory_bot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.50'
+description: |
+  Docsmith adds snapshot-based versioning to any ActiveRecord model with zero system dependencies.
+
+  • Full content snapshots (HTML, Markdown, JSON) for instant rollbacks
+  • Format-aware diff engine: word-level diffs for Markdown, tag-atomic diffs for HTML
+  • Document-level and range-anchored comments with threading and version migration
+  • Per-class configuration, debounced auto-save, lifecycle events, and a clean API
+
+  Perfect for wikis, CMS pages, API specs, legal documents, or any content that needs
+  an audit trail and inline collaboration.
+email:
+- swastik.thapaliya@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rspec_status"
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- USAGE.md
+- docs/superpowers/plans/2026-04-01-docsmith-full-plan.md
+- docs/superpowers/plans/2026-04-08-parsers-remove-branches-docs.md
+- docs/superpowers/specs/2026-04-01-docsmith-phase1-design.md
+- docsmith_spec.md
+- lib/docsmith.rb
+- lib/docsmith/auto_save.rb
+- lib/docsmith/comments/anchor.rb
+- lib/docsmith/comments/comment.rb
+- lib/docsmith/comments/manager.rb
+- lib/docsmith/comments/migrator.rb
+- lib/docsmith/configuration.rb
+- lib/docsmith/diff.rb
+- lib/docsmith/diff/engine.rb
+- lib/docsmith/diff/parsers/html.rb
+- lib/docsmith/diff/parsers/markdown.rb
+- lib/docsmith/diff/renderers.rb
+- lib/docsmith/diff/renderers/base.rb
+- lib/docsmith/diff/renderers/registry.rb
+- lib/docsmith/diff/result.rb
+- lib/docsmith/document.rb
+- lib/docsmith/document_version.rb
+- lib/docsmith/errors.rb
+- lib/docsmith/events/event.rb
+- lib/docsmith/events/hook_registry.rb
+- lib/docsmith/events/notifier.rb
+- lib/docsmith/rendering/html_renderer.rb
+- lib/docsmith/rendering/json_renderer.rb
+- lib/docsmith/version.rb
+- lib/docsmith/version_manager.rb
+- lib/docsmith/version_tag.rb
+- lib/docsmith/versionable.rb
+- lib/generators/docsmith/install/install_generator.rb
+- lib/generators/docsmith/install/templates/create_docsmith_tables.rb.erb
+- lib/generators/docsmith/install/templates/docsmith_initializer.rb.erb
+- sig/docsmith.rbs
+homepage: https://www.altcipher.com
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://www.altcipher.com
+  source_code_uri: https://github.com/swastik009/docsmith
+  changelog_uri: https://github.com/swastik009/docsmith/blob/main/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.27
+signing_key:
+specification_version: 4
+summary: Plug-and-play document version manager for Rails
+test_files: []